diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES.md | 30 | ||||
| -rw-r--r-- | doc/INSTALL-exim4.md | 7 | ||||
| -rw-r--r-- | doc/INSTALL.md | 36 | ||||
| -rw-r--r-- | doc/TRANSLATE.md | 89 |
4 files changed, 129 insertions, 33 deletions
diff --git a/doc/CHANGES.md b/doc/CHANGES.md index d80acec3c..025d72c8d 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -1,3 +1,33 @@ +# Version 0.5.1 + +## Highlighted features + +This release was mainly to address issue #418, a regression introduced +in 0.5, which was causing deployment problems: + +* Setting `STAGING_SITE: 0` in `general.yml` and running + `script/rails-post-deploy` will ensure the correct behaviour in + production environments +* It should now be safe to run `rake spec` on a production server + +There is one minor new feature in this release: + +* Administrators can follow the auto-login URLs forwarded in emails + from users who want support, and they will remain logged in as + themselves. + +We now have a most of a Czech translation (thanks Josef Pospisil!) + +Finally, this release also addresses a number of small bugs, including +the (potentially) important issue #408. + +As usual, there is a [full list of changes on github](https://github.com/sebbacon/alaveteli/issues?milestone=9&state=closed) + +## Upgrade notes + +* On a production server, ensure that `STAGING_SITE` is set to `0`, + and then run `script/rails-post-deploy` as usual. + # Version 0.5 ## Highlighted features diff --git a/doc/INSTALL-exim4.md b/doc/INSTALL-exim4.md index d7a0be40f..82c1aba45 100644 --- a/doc/INSTALL-exim4.md +++ b/doc/INSTALL-exim4.md @@ -6,7 +6,7 @@ In `/etc/exim4/conf.d/main/04_alaveteli_options`: ALAVETELI_HOME=/path/to/alaveteli/software ALAVETELI_USER=www-data log_file_path=/var/log/exim4/exim-%slog-%D - log_selector=+all -retry_defer + MAIN_LOG_SELECTOR==+all -retry_defer (The user ALAVETELI_USER should have write permissions on ALAVETELI_HOME). @@ -79,6 +79,11 @@ see something like: snafflerequest-234@localhost -> |/home/alaveteli/alaveteli/script/mailin transport = alaveteli_mailin_transport +This tells you that the routing part (making emails to +`foi\+.*@localhost` be forwarded to Alaveteli's `mailin` script) is +working. + There is a great [Exim Cheatsheet](http://bradthemad.org/tech/notes/exim_cheatsheet.php) online that you may find useful. + diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 9dd05b93e..8dbede290 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -283,6 +283,42 @@ is supplied in `../conf/varnish-alaveteli.vcl`. # Troubleshooting +* **Incoming emails aren't appearing in my Alaveteli install** + + First, you need to check that your MTA is delivering relevant + incoming emails to the `script/mailin` command. There are various + ways of setting your MTA up to do this; we have documented one way + of doing it in Exim at `doc/INSTALL-exim4.conf`, including a + command you can use to check that the email routing is set up + correctly. + + Second, you need to test that the mailin script itself is working + correctly, by running it from the command line, First, find a + valid "To" address for a request in your system. You can do this + through your site's admin interface, or from the command line, + like so: + + $ ./script/console + Loading development environment (Rails 2.3.14) + >> InfoRequest.find_by_url_title("why_do_you_have_such_a_fancy_dog").incoming_email + => "request-101-50929748@localhost" + + Now take the source of a valid email (there are some sample emails in + `spec/fixtures/files/`); edit the `To:` header to match this address; + and then pipe it through the mailin script. A non-zero exit code + means there was a problem. For example: + + $ cp spec/fixtures/files/incoming-request-plain.email /tmp/ + $ perl -pi -e 's/^To:.*/To: <request-101-50929748@localhost>/' /tmp/incoming-request-plain.email + $ ./script/mailin < /tmp/incoming-request-plain.email + $ echo $? + 75 + + The `mailin` script emails the details of any errors to + `CONTACT_EMAIL` (from your `general.yml` file). A common problem is + for the user that the MTA runs as not to have write access to + `files/raw_emails/`. + * **Various tests fail with "*Your PostgreSQL connection does not support unescape_bytea. Try upgrading to pg 0.9.0 or later.*"** diff --git a/doc/TRANSLATE.md b/doc/TRANSLATE.md index 639423f47..19d038472 100644 --- a/doc/TRANSLATE.md +++ b/doc/TRANSLATE.md @@ -3,45 +3,70 @@ resource files are managed in Transifex. The Transifex project is at https://www.transifex.net/projects/p/alaveteli/; you'll probably want -an account there (ask on the mailing list). +an account there (ask on the mailing list). It has a fairly easy to +use interface for contributing translations. -# Summary +# Translation process: translator's view -1. Make some changes to the software with `_('translatable strings')` -2. Temporarily move any theme containing translations out of the way (there's a bug in gettext_i18n_rails that can't cope with translation chains) -3. Run `./script/generate_pot.sh` -4. This should just cause the file at `locale/app.pot` to change. Commit and push -5. Move your theme back in place -6. Send a message to the alaveteli-dev mailing list warning them that you're going to upload this file to transifex -7. Wait a day or so to make sure they've uploaded any of their outstanding translations and have a copy of any old ones -8. Update the `app.pot` resource in Transifex -9. When new translations are available, run `tx pull -a` and commit the results to the repository +When a developer adds a new feature to the user interface in +Alaveteli, they use some code to mark sentences or words ("strings") +that they think will need to be translated. -# Detail +When the Alaveteli release manager is planning a release, they upload +a template containing all the strings to be translated (called a POT) +to Transifex. This causes your own translations in Transifex to be +updated with the latest strings. -## Finding new translatable strings +When you visit Transifex, it will prompt you to fill out values for +all new strings, and all strings that have been modified. In the case +where a string has only been slightly modified, such as with +punctuation ("Hello" has become "Hello!"), Transifex will suggest a +suitable translation for you (look for the "suggestions" tab under the +source string). -To update the POT file with strings from the software source, run -`rake gettext:find` from the Alaveteli software. This will also -update all the PO files for all the languages, which you don't -actually want, because these are all handled in Transifex; so you'll -want to revert these files again using git. +In order for this feature to work properly, the release manager has to +download your translations, run a program that inserts the +suggestions, and then upload them again. Therefore, when a release +candidate is announced, make sure you have uploaded any outstanding +translations, or you will lose them. -The script at `./script/generate_pot.sh` does these steps for you. +When a release candidate has been annouced, there is a **translation +freeze**: during this period, developers must not add any new strings +to the software, so you can be confident that you're translating +everything that will be in the final release. -When you've changed the POT file, and committed it, you should warn -people on the mailing list before logging into Transifex and pressing -the button to import it into that system. Otherwise, translators -might lose some of their old but useful translations. +The release manager will also give you a **translation deadline**. After +this date, you can continue to contribute new translations, but they +won't make it into the release. -## Pulling translations from Transifex - -To update the local translation files using the Transifex command-line client, first install it: +# Translation process: release manager's view - # easy_install transifex-client - -Then you can run the following from the root of your Alaveteli install: +Before the Alaveteli release manager cuts a new release branch, they +must: - tx pull -a - -Finally, commit these translations to github as usual. +* pick a date for the release branch to be cut ("release candidate date") +* make an announcement to the translators (using the "announcements" + feature in Transifex) that they should ensure they have any pending + translations saved in Transifex before the release candidate date +* make an announcement to the developers that all new strings should + be committed before the release candidate date +* on the release candidate date: + * download (`tx pull -a -f`) and commit all the current translations (important: + there's no revision history in Transifex!) + * regenerate the POT file and individual PO files for each language, + using `./script/generate_pot.sh` (which calls `rake gettext:find`, etc) + * this updates the PO template, but also merges it with the + individual PO files, marking strings that have only changed + slightly as "fuzzy" + * you must emporarily move any theme containing translations out of the way (there's a bug in gettext_i18n_rails that can't cope with translation chains) + * reupload (`tx push -t`) the POT and PO files to Transifex + * The point of uploading the PO files is that Transifex converts the "fuzzy" suggestions from Transifex into "suggestions" under each source string + * Note that Transifex *does not* preserve fuzzy strings in the PO files it makes available for download, on the grounds that Transifex supports multiple suggestions, whereas gettext only allows one fuzzy suggestion per msgid. + * remove the fuzzy strings from the local PO files (because they make + Rails very noisy), and then commit the result. You can do this by re-pulling from Transifex. +* on the release date: + * download and commit all the current translations + +# Translations: developers' view + +See the [I18n guide](https://github.com/sebbacon/alaveteli/wiki/I18n-guide) on the wiki. |