diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES.md | 38 | ||||
| -rw-r--r-- | doc/INSTALL-exim4.md | 17 | ||||
| -rw-r--r-- | doc/INSTALL.md | 38 | ||||
| -rw-r--r-- | doc/THEMES.md | 13 | ||||
| -rw-r--r-- | doc/TRANSLATE.md | 30 |
5 files changed, 100 insertions, 36 deletions
diff --git a/doc/CHANGES.md b/doc/CHANGES.md index dbea64bda..0abbeec82 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -16,7 +16,7 @@ * A new, experimental theme for the administrative interface. It's currently packaged as a standalone theme, but will be merged into the core once it's been tested and iterated in production a few - times. + times. Thanks to @wombleton for kicking this off! * Alert subscriptions are now referred to as "following" a request (or group of requests) throughout the UI. When a user "follows" a request, updates regarding that request are posted on a new "wall" @@ -26,12 +26,13 @@ button for users to report potentially unsuitable requests, and a form control in the administrative interface that hides a request and sends the user an email explaining why. +* A bug which prevented locales containing underscores (e.g. `en_GB`) + was fixed + ([issue #503](https://github.com/sebbacon/alaveteli/issues/503)) +* Error pages are now presented with styling from themes ## Upgrade notes -* Existing installations will need to install the Bundler gem. See - `INSTALL.md` for details. - * As a result of using bundler, the list of software packages that should be installed has changed. On Debian, you can run: @@ -40,10 +41,13 @@ [This gist](https://gist.github.com/2584766) shows the changes to `config/packages` since the previous release. +* Existing installations will need to install Bundler. On Debian this + is done by the above command. See `INSTALL.md` for details. + * Because dependencies are now handled by Bundler, when you next run the `rails-post-deploy` script, it will download, compile and - install various things. Part of this is compiling xapian, which may - take a *long* time (subsequent deployments should be much faster) + install various things. Part of this is compiling xapian, which will + take a *long* time (subsequent deployments will be much faster) * To support invalidating the Varnish cache, ensure that there's a value for `VARNISH_HOST` in `general.yml` (normally this would be @@ -53,7 +57,12 @@ you leave `VARNISH_HOST` blank, it will have no effect. Finally, you should install the `purge-varnish` init script that's provided in `ugly` format at `config/purge-varnish-debian.ugly` to ensure the - purge queue is emptied regularly. + purge queue is emptied regularly. Once deployed, you should also + check your production log for lines starting `PURGE:` to ensure the + purges are successful (a failure will typically be due to a + misconfigured Varnish). If purges are unsuccessful, the conseqence + is that individual request pages that are served to anonymous users + will be up to 24 hours out of date. * Administrators are now assumed to log in using standard user accounts with superuser privileges (see 'Administrator Privileges' in @@ -67,7 +76,20 @@ `./script/rails-post-deploy`. If you don't like it, turn it off again by removing the line referring to the theme (`adminbootstraptheme`) -- but email the mailing list first, - explaining why! + explaining why! The intention is to merge this theme into the + Alaveteli core in a future release. + +* If you are already using Google Analytics, you are probably + including the tracking code manually in your theme. If you'd like + to use Alaveteli's support for Google Analytics, set the `GA_CODE` + in `general.yml` and remove all reference to the tracking code from + your theme. + +* Here's a list of all the new config variables you might want to change: + * `THEME_URLS` + * `SKIP_ADMIN_AUTH` + * `VARNISH_HOST` + * `GA_CODE` # Version 0.5.2 diff --git a/doc/INSTALL-exim4.md b/doc/INSTALL-exim4.md index 84f105c57..91c3506d3 100644 --- a/doc/INSTALL-exim4.md +++ b/doc/INSTALL-exim4.md @@ -40,17 +40,20 @@ content: ^foi\\+.*: |/path/to/alaveteli/software/script/mailin -You should also configure exim to discard any messages sent to the `BLACKHOLE_PREFIX` -address, whose default value is 'do-not-reply-to-this-address'. For example, add the -following to config/aliases: +You should also configure exim to discard any messages sent to the +`BLACKHOLE_PREFIX` address, whose default value is +'do-not-reply-to-this-address'. For example, add the following to +config/aliases: # We use this for envelope from for some messages where we don't care about delivery do-not-reply-to-this-address: :blackhole: -If you want to make use of the automatic bounce-message handling, then set the `TRACK_SENDER_EMAIL` -address to be filtered through `script/handle-mail-replies`. Messages that are not bounces or -out-of-office autoreplies will be forwarded to `FORWARD_NONBOUNCE_RESPONSES_TO`. For example, -in WhatDoTheyKnow the configuration looks like this: +If you want to make use of the automatic bounce-message handling, then +set the `TRACK_SENDER_EMAIL` address to be filtered through +`script/handle-mail-replies`. Messages that are not bounces or +out-of-office autoreplies will be forwarded to +`FORWARD_NONBOUNCE_RESPONSES_TO`. For example, in WhatDoTheyKnow the +configuration looks like this: raw_team: [a list of people on the team] team: |/path/to/alaveteli/software/script/handle-mail-replies diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 2ebc21dab..ef354c5ce 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -63,7 +63,9 @@ explanation): sudo ruby1.8 /tmp/rubygems-1.6.2/setup.rb To install Alaveteli's Ruby dependencies, we also need to install -bundler: +bundler. In Debian, this is provided as a package (installed as part +of the package install process above). You could also install it as a +gem: sudo gem1.8 install bundler @@ -222,17 +224,6 @@ One of the things the script does is install dependencies (using `bundle install`). Note that the first time you run it, part of the `bundle install` that compiles `xapian-full` takes a *long* time! -On Debian, at least, the binaries installed by bundler are not put in -the system `PATH`; therefore, in order to run `rake` (needed for -deployments), you will need to do something like: - - ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ - -Or (Debian): - - ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ - - If you want some dummy data to play with, you can try loading the fixtures that the test suite uses into your development database. You can do this with: @@ -374,6 +365,15 @@ further action. You should read the `CHANGES.md` document to see what's changed since your last deployment, paying special attention to anything in the "Updgrading" sections. +Any upgrade may include new translations strings, i.e. new or altered +messages to the user that need translating to your locale. You should +visit Transifex and try to get your translation up to 100% on each new +release. Failure to do so means that any new words added to the +Alaveteli source code will appear in your website in English by +default. If your translations didn't make it to the latest release, +you will need to download the updated `app.po` for your locale from +Transifex and save it in the `locales/` folder. + You should always run the script `scripts/rails-post-deploy` after each deployment. This runs any database migrations for you, plus various other things that can be automated for deployment. @@ -462,3 +462,17 @@ various other things that can be automated for deployment. from source, and finally executing `sudo gem update --system 1.6.2`. +* **I'm seeing `rake: command not found` when running the post install script + + The script uses `rake`. + + It may be that the binaries installed by bundler are not put in the + system `PATH`; therefore, in order to run `rake` (needed for + deployments), you may need to do something like: + + ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ + + Or (Debian): + + ln -s /usr/lib/ruby/gems/1.8/bin/rake /usr/local/bin/ + diff --git a/doc/THEMES.md b/doc/THEMES.md index 55c0c017f..50335c082 100644 --- a/doc/THEMES.md +++ b/doc/THEMES.md @@ -44,6 +44,19 @@ This downloads and installs the theme in `vendor/plugins/alavetelitheme` and contains examples for nearly everything you might want to customise. +# Make sure your theme is as lightweight as possible + +The more you put in your theme, the harder it will be to upgrade to +future versions of Alaveteli. Everything you place in your theme +overrides things in the core theme, so if you make a new "main +template", then new widgets that appear in the core theme won't appear +on your website. + +Therefore, you should consider how you can brand your website without +changing much in the core theme. The ideal would be if you are able +to rebrand the site by only changing the CSS. You will also need to +add custom help pages, as described below. + # Branding the site The core templates that comprise the layout and user interface of an diff --git a/doc/TRANSLATE.md b/doc/TRANSLATE.md index 19d038472..8330c5f24 100644 --- a/doc/TRANSLATE.md +++ b/doc/TRANSLATE.md @@ -53,19 +53,31 @@ must: * 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) + * you should also commit these translations to a hotfix for the + previous version, so they are preserved against the last known + good msgids + * regenerate the POT file and individual PO files for each + language, using `bundle exec rake + gettext:store_model_attributes`, followed by `bundle exec rake + rake gettext:find` * 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. + * reupload (`tx push -s -t`) the POT and PO files to Transifex to the + current release branch + * 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 + * download and commit all the current translations to the current + release branch # Translations: developers' view |