diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES.md | 13 | ||||
| -rw-r--r-- | doc/INSTALL.md | 33 | ||||
| -rw-r--r-- | doc/THEMES.md | 59 | ||||
| -rw-r--r-- | doc/TRANSLATE.md | 14 |
4 files changed, 93 insertions, 26 deletions
diff --git a/doc/CHANGES.md b/doc/CHANGES.md index 758e6b56e..d80acec3c 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -6,14 +6,23 @@ * It is now possible to rebuild the xapian index for specific terms, rather than having to drop and rebuild the entire database every time (as previously). See rake xapian:rebuild_index for more info. * When listing authorities, show all authorities in default locale, rather than only those in the currently selected locale. * Ensure incoming emails are only ever parsed once (should give a performance boost) +* Added a simple rate-limiting feature: restrict the number of requests users can make per day, except if explicitly unrestricted in the admin interface +* [Full list of changes on github](https://github.com/sebbacon/alaveteli/issues?state=closed&milestone=9) ## Upgrade notes -* **IMPORTANT! We now depend on Xapian 1.2**, which means you may need to install Xapian from backports. See [issue #159] for more info. +* **IMPORTANT! We now depend on Xapian 1.2**, which means you may need to install Xapian from backports. See [issue #159](https://github.com/sebbacon/alaveteli/issues/159) for more info. * Themes created for 0.4 and below should be changed to match the new format (although the old way should continue to work): * You should create a resources folder at `<yourtheme>/public/` and symlink to it from the main rails app. See the `install.rb` in `alaveteli-theme` example theme for details. * Your styles should be moved from `general/custom_css.rhtml` to a standalone stylesheet in `<yourtheme>/public/stylesheets/` * The partial at `general/_before_head_end.rhtml` should be changed in the theme to include this stylesheet - +* [issue #281](https://github.com/sebbacon/alaveteli/issues/281) fixes some bugs relating to display of internationalised emails. To fix any wrongly displayed emails, you'll need to run the script at `script/clear-caches` so that the caches can be regenerated +* During this release, a bug was discovered in pdftk 1.44 which caused it to loop forever. Until it's incorporated into an official release, you'll need to patch it yourself or use the Debian package compiled by mySociety (see link in [issue 305](https://github.com/sebbacon/alaveteli/issues/305)) +* Ensure you have values for new config variables (see `config/general.yml-example`): + * EXCEPTION_NOTIFICATIONS_FROM + * EXCEPTION_NOTIFICATIONS_TO +* The new optional config variable MAX_REQUESTS_PER_USER_PER_DAY can be set to limit the number of requests each user can make per day. +* The recommended Varnish config has changed, so that we ignore more cookies. You should review your Varnish config with respect to the example at `config/varnish-alaveteli.vcl`. +* Consider setting elinks global config as described in the "Troubleshooting" section of INSTALL.md # Version 0.4 diff --git a/doc/INSTALL.md b/doc/INSTALL.md index a666ac2f0..9dd05b93e 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -36,21 +36,31 @@ Some of the files also have a version number listed in config/packages - check that you have appropriate versions installed. Some also list "|" and offer a choice of packages. + You will also want to install mySociety's common ruby libraries and the Rails code. Run: - git submodule update --init + git submodule update --init to fetch the contents of the submodules. -Optionally, you may want to install -[wkhtmltopdf](http://code.google.com/p/wkhtmltopdf/downloads/list). +If you would like users to be able to download pretty PDFs as part of +the downloadable zipfile of their request history, you should also install +[wkhtmltopdf](http://code.google.com/p/wkhtmltopdf/downloads/list). We recommend downloading the latest, statically compiled version from the project website, as this allows running headless (i.e. without a graphical interface running) on Linux. If you do install `wkhtmltopdf`, you need to edit a setting in the config file to point -to it (see below). +to it (see below). If you don't install it, everything will still work, but +users will get ugly, plain text versions of their requests when they +download them. +Version 1.44 of `pdftk` contains a bug which makes it to loop forever +in certain edge conditions. Until it's incorporated into an official +release, you can either hope you don't encounter the bug (it ties up a +rails process until you kill it) you'll need to patch it yourself or +use the Debian package compiled by mySociety (see link in +[issue 305](https://github.com/sebbacon/alaveteli/issues/305)) # Configure Database @@ -77,8 +87,8 @@ constraints whilst running the tests they also need to be a superuser. The following command will set up a user 'foi' with password 'foi': - echo "CREATE DATABASE foi_development encoding = 'UTF8'; - CREATE DATABASE foi_test encoding = 'UTF8'; + echo "CREATE DATABASE foi_development encoding 'SQL_ASCII' template template0; + CREATE DATABASE foi_test encoding 'SQL_ASCII' template template0; CREATE USER foi WITH CREATEUSER; ALTER USER foi WITH PASSWORD 'foi'; ALTER USER foi WITH CREATEDB; @@ -86,6 +96,12 @@ The following command will set up a user 'foi' with password 'foi': GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi; ALTER DATABASE foi_development OWNER TO foi; ALTER DATABASE foi_test OWNER TO foi;" | psql + +We create using the ``SQL_ASCII`` encoding, because in postgres this +is means "no encoding"; and because we handle and store all kinds of +data that may not be valid UTF (for example, data originating from +various broken email clients that's not 8-bit clean), it's safer to be +able to store *anything*, than reject data at runtime. # Configure email @@ -295,8 +311,9 @@ is supplied in `../conf/varnish-alaveteli.vcl`. to `/etc/elinks/elinks.conf`: set document.codepage.assume = "utf-8" - - You should also check that your locale is set up wrongly. See + set document.codepage.force_assumed = 1 + + You should also check that your locale is set up correctly. See [https://github.com/sebbacon/alaveteli/issues/128#issuecomment-1814845](this issue followup) for further discussion. diff --git a/doc/THEMES.md b/doc/THEMES.md index c2381b61f..55c0c017f 100644 --- a/doc/THEMES.md +++ b/doc/THEMES.md @@ -4,7 +4,11 @@ might want to do to customise it, beyond the available settings in the The most common requirement is to brand the site: at a minimum, inserting your own logo and colour scheme. You may also want to tweak -the different states that a request can go through. +the different states that a request can go through. You'll also want +to edit the categories that public bodies can appear in (i.e. the +groupings on the left hand side of the +"[View authorities](http://www.whatdotheyknow.com/body/list/all)" page +on WhatDoTheyKnow. There may also be other things you want to customise; drop a line on the developer's mailing list to discuss, if so. We're still working @@ -35,6 +39,10 @@ This document is about what you can do in a theme. To get started, install the sample theme by running ./script/plugin install git://github.com/sebbacon/alavetelitheme.git + +This downloads and installs the theme in +`vendor/plugins/alavetelitheme` and contains examples for nearly +everything you might want to customise. # Branding the site @@ -44,16 +52,23 @@ For example, the template for the home page lives at `app/views/general/frontpage.rhtml`, and the template for the "about us" page is at `app/views/help/about.rhtml`. -Any of these pages can be overridden in your own theme, by placing -them at a corresponding location within your theme's `lib/` directory. -These means that a file at -`vendor/plugins/alavetelitheme/lib/help/about.rhml` will appear in -place of the core "about us" file. +Obviously, you *could* edit those core files directly, but this would +be a Bad Idea, because you would find it increasingly hard to do +upgrades. Having said that, sometimes you may want to change the core +templates in a way that would benefit everyone, in which case, discuss +the changes on the mailing list, make them in a fork of Alaveteli, and +then issue a pull request. + +Normally, however, you should override these pages **in your own +theme**, by placing them at a corresponding location within your +theme's `lib/` directory. These means that a file at +`vendor/plugins/alavetelitheme/lib/help/about.rhml` will appear +instead of the core "about us" file. Rails expects all its stylesheets to live at `<railshome>/public`, which presents a problem for plugins. Here's how we solve it: the stylesheet and associated resources for your theme live (by -convention) in at `alavatelitheme/public/`. This is symlinked from +convention) in at `alavetelitheme/public/`. This is symlinked from the main Rails app -- see `alavetelitheme/install.rb` to see how this happens. @@ -64,7 +79,18 @@ custom CSS in your theme's stylesheet folder (by convention, in <%= stylesheet_link_tag "/alavetelitheme/stylesheets/custom" %> -...which will, of course, need changing for your theme. +...which will, usually, need changing for your theme. + +# Adding your own categories for public bodies + +Categories are implemented in Alaveteli using tags. Specific tags can +be designated to group authorities together as a category. + +There's a file in the sample theme, +`alavetelitheme/lib/public_body_categories_en.rb`, which contains a +nested structure that defines categories. It contains a comment +describing its structure. You should make a copy of this file for each +locale you support. # Customising the request states @@ -75,12 +101,14 @@ as "overdue" in the main site config file. If you can't live with the states as they are, there's a very basic way to add to them (which will get improved over time). There's not -currently a way to remove any. +currently a way to remove any easily. There is an example of how to +do this in the `alavetelitheme`. -To do this, create two modules in your theme, +To do add states, create two modules in your theme, `InfoRequestCustomStates` and `RequestControllerCustomStates`. The former must have these two methods: +* `theme_calculate_status`: return a tag to identify the current state of the request * `theme_extra_states`: return a list of tags which identify the extra states you'd like to support * `theme_display_status`: return human-readable strings corresponding with these tags @@ -107,3 +135,14 @@ You can see examples of these customisations in for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the file `lib/views/general/_custom_state_transitions.rhtml`, which is unused). + +# Adding new pages in the navigation + +`alavetelitheme/lib/config/custom-routes.rb` allows you to extend the base routes in +Alaveteli. The example in `alavetelitheme` adds an extra help page. +You can also use this to override the behaviour of specific pages if +necessary. + +# Adding or overriding models and controllers + +If you need to extend the behaviour of Alaveteli at the controller or model level, see `alavetelitheme/lib/controller_patches.rb` and `alavetelitheme/lib/model_patches.rb` for examples. diff --git a/doc/TRANSLATE.md b/doc/TRANSLATE.md index be88dafa0..639423f47 100644 --- a/doc/TRANSLATE.md +++ b/doc/TRANSLATE.md @@ -8,12 +8,14 @@ an account there (ask on the mailing list). # Summary 1. Make some changes to the software with `_('translatable strings')` -2. Run `./script/generate_pot.sh` -3. This should just cause the file at `locale/app.pot` to change. Commit and push -4. Send a message to the alaveteli-dev mailing list warning them that you're going to upload this file to transifex -5. Wait a day or so -6. Update the `app.pot` resource in Transifex -7. When new translations are available, run `tx pull -a` and commit the results to the repository +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 # Detail |