diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/customising/themes.md | 371 | ||||
| -rw-r--r-- | docs/customising/translation.md | 11 | ||||
| -rw-r--r-- | docs/developers/i18n.md | 8 | ||||
| -rw-r--r-- | docs/getting_started.md | 21 | ||||
| -rw-r--r-- | docs/glossary.md | 380 | ||||
| -rw-r--r-- | docs/installing/deploy.md | 2 | ||||
| -rw-r--r-- | docs/installing/macos.md | 14 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 7 | ||||
| -rw-r--r-- | docs/installing/next_steps.md | 14 | ||||
| -rw-r--r-- | docs/installing/vagrant.md | 51 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 490 | ||||
| -rw-r--r-- | docs/running/categories_and_tags.md | 196 | ||||
| -rw-r--r-- | docs/running/holding_pen.md | 101 | ||||
| -rw-r--r-- | docs/running/requests.md | 322 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 29 |
15 files changed, 1782 insertions, 235 deletions
diff --git a/docs/customising/themes.md b/docs/customising/themes.md index a51ed447e..a2b498084 100644 --- a/docs/customising/themes.md +++ b/docs/customising/themes.md @@ -21,27 +21,93 @@ You don't need to be a programmer in order to make simple changes, but you will need to be confident enough to copy and change some files. If you're not sure about this, [ask for help](/community/)! +<div class="attention-box info"> + A theme is the way you tell Alaveteli which parts of your site look and behave + differently from the core site. These differences are implemented as a + collection of files (separate from the core Alaveteli source code), which + Alaveteli uses to override its default code. +</div> + +<div class="attention-box warning"> + When you customise Alaveteli, you should <strong>always use this + theme mechanism</strong> instead of editing the core Alaveteli files. If you + do not — that is, if you make custom changes to the main Alaveteli + source code — you may not be able to update your site with newer + Alaveteli code (new features and occassional bugfixes). + <p> + <em>Sometimes</em> you may want to change the core templates in a way that + would benefit everyone, in which case: great! But please discuss the changes + on the mailing list first, make them in a fork of Alaveteli, and then issue + a pull request. + </p> +</div> + +## Your theme is a separate repo + + +We use +<a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">git</a> +to manage Alaveteli's source code, and Alaveteli expects your theme to be in +a git repository of its own. + +Although you *can* start customising your site on your +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a> +by playing with the `alavetelitheme` theme that Alaveteli ships with, we recommend +you make it into your own repo as soon as you can. If you're seriously customising +— and certainly before you can deploy to a +<a href="{{ site.baseurl }}docs/glossary/#production" class="glossary__link">production server</a> — +you must do this. Make sure you choose a unique name for your theme (and hence its +repo). If your site is `abcexample.com`, we suggest you call your theme +something like `abcexample-theme`. + +Alaveteli's `themes:install` rake task, which installs themes, works by +getting the git repo from the URL specified in the config setting +[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls). This is +why your theme must be in its own git repo. + +One way to create your own theme is to fork the `alavetelitheme` theme from +[https://github.com/mysociety/alavetelitheme](https://github.com/mysociety/alavetelitheme) +(giving it your own theme name), edit it or add files, and deploy it with `themes:install`. +Alternatively, since your site already has the default theme's files within it, +you can duplicate `alivetelitheme` (in `lib/themes/`) and change its name. + +<div class="attention-box helpful-hint"> + Here's an example of a complex theme in action: see the theme repo at + <a href="https://github.com/mysociety/whatdotheyknow-theme">https://github.com/mysociety/whatdotheyknow-theme</a>. + This is the theme for UK's Alaveteli instance + <a href="{{ site.baseurl}}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>. + You can see it + <a href="https://www.whatdotheyknow.com">deployed on the WhatDoTheyKnow website</a>. + This happens because the WhatDoTheyKnow server has this setting in <code>config/general.yml</code>: + </p> + <pre><code>THEME_URLS: + - 'git://github.com/mysociety/whatdotheyknow-theme.git'</code></pre> +</div> + ## What you might want to change The most common requirement is to brand the site: at a minimum, -[inserting your own logo](#changing-the-logo) and [colour scheme](#changing-the-colour-scheme). You may also want to tweak -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](https://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 what you need. We're still working -out the best way of doing these kinds of customisations! - -In any case, the important principle to bear in mind is that the less -you override and customise the code, the easier your site will be to -maintain in the long term. Any customisation is possible, but for -each customisation beyond the simple cases documented here, ask -yourself (or your client), "can we possibly live without this?" If the -answer is "no", then consider starting a discussion about a pluggable -way of achieving your goals, rather than overriding any of the core +[inserting your own logo](#changing-the-logo) and +[colour scheme](#changing-the-colour-scheme). You should also +[add the categories](#adding-your-own-categories-for-authorities) +that authorities can appear in (you can see these as groupings on the left-hand +side of the [View authorities](https://www.whatdotheyknow.com/body/list/all) page +on <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>). +You may also want to +[tweak the different states](#customising-the-request-states) that a request can +go through. + +There may also be other things you want to customise -- talk to us on the +developer's mailing list to discuss what you need. We're happy to help work out +the best way of doing customisation and it's even possible that what you want +has already been done in someone else's theme. + +The important principle to bear in mind is that the less you override and +customise the code, the easier your site will be to maintain in the long term. +Any customisation is possible, but for each customisation beyond the simple +cases documented here, ask yourself (or your client), "can we possibly live +without this?" If the answer is "no", then always ask on the mailing list about +a pluggable way of achieving your goals before you override any of the core code. ## General principles @@ -49,120 +115,172 @@ code. We try to encapsulate all site-specific functionality in one of these places: -* Site [configuration]({{ site.baseurl }}docs/customising/config/) - (e.g., the name of your site, the available - languages, and so on — all in `config/general.yml`) -* Data (e.g. the public bodies to whom requests should be addressed) -* A theme, installed in `lib/themes`. +* **site configuration**<br> + use the [config settings]({{ site.baseurl }}docs/customising/config/) + for example, the name of your site, the available languages, and so on. + You change these by editing `config/general.yml`. +* **data**<br> + for example, the public authorities to whom requests should be addressed, + and the tags and categories for grouping them. You control all this + through the + <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin + interface</a>: see the [admin manual]({{ site.baseurl }}docs/running/admin_manual). +* **a theme**<br> + installed in `lib/themes`. + The page you're reading now is all about what you can do in a theme. -This document is about what you can do in a theme. +By default, Alaveteli ships with the sample theme (`alavetelitheme`), so your +`config/general.yml` contains this: -By default, the sample theme ("alavetelitheme") has already been -installed. See the setting -[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls) -in `general.yml` for an explanation. + THEME_URLS: + - 'git://github.com/mysociety/alavetelitheme.git' -You can also install the sample theme by hand, by running: +You can also install the theme by hand, by running: bundle exec rake themes:install +This installs whichever theme is specified by the +[`THEME_URLS`]({{ site.baseurl }}docs/customising/config/#theme_urls) +setting. + The sample theme contains examples for nearly everything you might -want to customise. You should probably make a copy, rename it, and +want to customise. We recommend you make a copy, rename it, and use that as the basis for your own theme. +<div class="attention-box info"> + The + <code><a href="{{ site.baseurl }}docs/customising/config/#theme_urls">THEME_URLS</a></code> + setting allows you to specifiy more than one theme — but + normally you only need one. +</div> + ## 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. +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. If you want them, you'll need to manually update +your version of the template to include them, and potentially you'll need to +do this every time the core theme changes. -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. +Therefore, you should consider how you can brand your website by changing +as little in the core theme as possible. An extreme -- but not impossible -- +way to do this is to rebrand the site by only changing the CSS, because this +means *none* of the templates are being overridden. + +However, even with minimal customisation, you must also add custom help pages +(described below). Alaveteli's default help pages are deliberately incomplete. +We know that every installation is going to be operating in different +circumstances, so a generic help text cannot be useful. You must write your +own, for your own users. ## Branding the site -The core templates that comprise the layout and user interface of an -Alaveteli site live in `app/views/`. They use Rails' ERB syntax. -For example, the template for the home page lives at -`app/views/general/frontpage.html.erb`, and the template for the "about -us" page is at `app/views/help/about.html.erb`. - -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 -`lib/themes/alavetelitheme/lib/views/help/about.html.erb` will appear -instead of the core "about us" file. +The core templates define the layout and user interface of an Alaveteli site. +They are in `app/views/` and use +<a href="{{ site.baseurl }}" class="glossary__link">Rails</a>' +ERB syntax. For example, the template for the home page lives at +`app/views/general/frontpage.html.erb`, and the template for the "about us" +page is at `app/views/help/about.html.erb`. + +As described above, although you *could* edit those core files directly, this +would be a Bad Idea, because you would find it increasingly hard to do upgrades. + +Instead, you should override these pages *in your own theme*, by placing them +at a corresponding location within your theme's `lib/` directory. For example, +this means that if you put your own copy of the "about us" template +in <code>lib/themes/<em>yourtheme</em>/lib/views/help/about.html.erb</code>, +then that will appear instead of the core "about us" file. ### Changing the logo -Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) to convert and compress stylesheets written in -<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a>, -the css extension language, to minified concatenated css. Assets are stored in core Alaveteli under `app/assets` - in `fonts`, `images`, `javascripts` and `stylesheets`. -The default theme has corresponding asset directories in `alavetelitheme/assets` Asset files placed in these directories will override those in the core directories. As with templates, a file at `lib/themes/alavetelitheme/assets/images/logo.png` will appear on the site instead of the logo from `app/assets/images/logo.png`. +Alaveteli uses Rails' [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) +to convert and compress stylesheets written in +<a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> +into minified concatenated CSS. Assets are stored in core Alaveteli under +`app/assets` -- in `fonts`, `images`, `javascripts` and `stylesheets`. The +default theme has corresponding asset directories in `alavetelitheme/assets` +Asset files placed in these directories will override those in the core +directories. As with templates, a file at +<code>lib/themes/<em>yourtheme</em>/assets/images/logo.png</code> will appear on the +site instead of the logo from `app/assets/images/logo.png`. ### Changing the colour scheme Alaveteli uses a set of basic <a href="{{ site.baseurl }}docs/glossary/#sass" class="glossary__link">Sass</a> -modules to define the layout for the site on different device sizes, and some basic styling. These modules are in `app/assets/stylesheets/responsive`. The colours and fonts are added in the theme - alavetelitheme defines them in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours used in the theme are defined as variables at the top of this file and you can edit them here. +modules to define the layout for the site on different device sizes, and some +basic styling. These modules are in `app/assets/stylesheets/responsive`. The +colours and fonts are added in the theme -- `alavetelitheme` defines them in +`lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Colours +used in the theme are defined as variables at the top of this file and you can +edit them in your version of this file in your own theme. ### Changing other styling -To change other styling, you can add to or edit the styles in `lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. Styles defined here will override those in the sass modules in `app/assets/stylesheets/responsive` as they will be imported last by `app/assets/stylesheets/responsive/all.scss`. However, if you want to substantially change the way a particular part of the site is laid out, you may want to override one of the core sass modules. You could override the layout of the front page, for example, by copying `app/assets/stylesheets/responsive/_frontpage_layout.scss` to `lib/themes/alavetelitheme/assets/stylesheets/responsive/_frontpage_layout.scss` and editing it. - -You can load extra stylesheets and javascript files by adding them to `lib/themes/alavetelitheme/lib/views/general/_before_head_end.html.erb` - -## Adding your own categories for public bodies - -Categories are implemented in Alaveteli using tags. Specific tags can be -used to group authorities together as a category. Categories themselves -are grouped under category headings on the side of the "View -authorities" page. You can create, edit and reorder categories and -category headings in the admin interface, from the "Categories" admin -menu item. You can apply the category tags you have created to -authorities under the "Authorities" admin menu item. For an authority to -appear under a category, the category's "category tag" must be one of -the tags applied to the authority. +To change other styling, you can add to or edit the styles in +`lib/themes/alavetelitheme/assets/stylesheets/responsive/custom.scss`. +Styles defined here will override those in the sass modules in +`app/assets/stylesheets/responsive` as they will be imported last by +`app/assets/stylesheets/responsive/all.scss`. However, if you want to +substantially change the way a particular part of the site is laid out, +you may want to override one of the core Sass modules. You could override the +layout of the front page, for example, by copying +`app/assets/stylesheets/responsive/_frontpage_layout.scss` to +<code>lib/themes/<em>yourtheme</em>/assets/stylesheets/responsive/_frontpage_layout.scss</code> +and editing it. + +You can load extra stylesheets and javascript files by adding them to +<code>lib/themes/<em>yourtheme</em>/lib/views/general/_before_head_end.html.erb</code> + +## Adding your own categories for authorities + +You should add +<a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> +for the authorities on your site -- Alaveteli will display the authorities grouped +by categories if you have set any up. Alaveteli uses +<a href="{{ site.baseurl }}docs/glossary/#tag" class="glossary__link">tags</a> +to assign authorities to the right categories, but you should add tags anyway +because they are also used by the site's search facility. Together, categories +and tags help your users find the right authority for their request. + +You can set all this up using the +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>. +See [more about categories and tags]({{ site.baseurl }}docs/running/categories_and_tags/) +for details. ## Customising the request states As mentioned above, if you can possibly live with the [default Alaveteli request statuses]({{ site.baseurl }}docs/customising/states/), -it would be good to do so. Note that you can set how many days counts -as "overdue" in the main site config file — +it would be good to do so. You can set how many days must pass before +a request is considered "overdue" in the main site config file — see [`REPLY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#reply_late_after_days). -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 easily. There is an example of how to -do this in the `alavetelitheme`. +If you can't live with the states as they are, there's a very basic way to add +to them (we're working on this, so it will be improved over time). Currently, +there's no easy way to remove any. There is an example of how to do this in the +`alavetelitheme`. To do add states, create two modules in your theme, -`InfoRequestCustomStates` and `RequestControllerCustomStates`. The -former must have these methods: +`InfoRequestCustomStates` and `RequestControllerCustomStates`. + +`InfoRequestCustomStates` must have these 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 -The latter must have one method: +`RequestControllerCustomStates` must have one method: -* `theme_describe_state`: Return a notice for the user suitable for +* `theme_describe_state`: return a notice for the user suitable for displaying after they've categorised a request; and redirect them to a suitable next page -When you've added your extra states, you also need to create the following files in your theme: +When you've added your extra states, you also need to create the following files +in your theme: * `lib/views/general/_custom_state_descriptions.html.erb`: Descriptions of your new states, suitable for displaying to end users @@ -171,26 +289,85 @@ When you've added your extra states, you also need to create the following files 'completion' states, for displaying on the categorisation form that we ask requestors to fill out * `lib/views/general/_custom_state_transitions_pending.html.erb`: As - above, but for new states you might characterise as 'pending' + above, but for new states you might characterise as *pending* states. You can see examples of these customisations in [this commit](https://github.com/sebbacon/informatazyrtare-theme/commit/2b240491237bd72415990399904361ce9bfa431d) for the Kosovan version of Alaveteli, Informata Zyrtare (ignore the -file `lib/views/general/_custom_state_transitions.html.erb`, which is +file `_custom_state_transitions.html.erb`, which is unused). +## Customising the help pages + +The help pages are a really important part of an Alaveteli site. If you're running Alaveteli in another language, you'll want to show +your users localised versions of the help pages. Even if you're running +the site in English, the default help pages in Alaveteli are taken from +WhatDoTheyKnow, and are therefore relevant only to the UK. You should +take these pages as inspiration, but review their content with a view to +your jurisdiction. + +The important pages to customise and translate are listed here. We note where Alaveteli links to these pages (sometimes to anchors for particular sections within the pages) or takes users directly to them. + +* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb): why the website exists, why it works, etc. When a user starts to make a request in Alaveteli, they are referred to the section here on [why authorities should respond to requests](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.html.erb#L29). + +* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.html.erb): how to get in touch + +* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb): who is involved in the site. Importantly, includes [a section](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.html.erb#L71) on how users can help the project. Users are referred to this section if they categorise all the requests in the [categorisation game]({{ site.baseurl }}docs/glossary/#categorisation-game). + +* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.html.erb): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. + +* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. Users are referred to the [section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.html.erb#L114) about what to do if the authority says they only have a paper copy of the information requested if the user classifies their request as ['gone postal']({{ site.baseurl }}docs/customising/states/#gone_postal). + +* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. Users are referred to the [section on how quickly a response to their request should arrive](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L125) when their request is overdue for a response. They are referred to the [section on what to do if the Alaveteli site isn't showing the authority they want to request information](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.html.erb#L30) from the page that allows them to list and search authorities. + +* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. In particular users are referred to the [section on using other means](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L83) to get their question answered. If the user has requested an internal review of their request, they are referred to [the section on this page](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.html.erb#L28) that describes the law relating to how long a review should take. + +* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.html.erb): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have ["gone postal"]({{ site.baseurl }}docs/customising/states/#gone_postal) - where the authority has asked for the user's physical address so that they can reply with a paper response. + +* [sidebar](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_sidebar.html.erb): a menu for the help pages with a link to each one. You should customise this so that it includes any extra help pages you add, and doesn't include any you remove. + +You can add your own help pages to your site by replacing the default +pages in your theme with your own versions, using a locale suffix for +each page to indicate what language the page is written in. No locale +suffix is needed for pages written for the [default locale]({{ site.baseurl }}docs/customising/config/#default_locale) for the site. +For example, [alavetelitheme contains help +pages](https://github.com/mysociety/alavetelitheme/tree/master/lib/views/help) +for the default 'en' locale and an example Spanish 'about' page. If no +help page exists in the theme for a particular page in the locale that +the site is being viewed in, the default help page in English will be +shown. + + ## 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. +You can extend the base routes in Alaveteli by modifying +<code>lib/themes/<em>yourtheme</em>/lib/config/custom-routes.rb</code>. +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. +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. + +## Quickly switching between themes + +On your +<a href="{{ site.baseurl }}docs/glossary/#development" class="glossary__link">development server</a>, +you can use +[`script/switch-theme.rb`](https://github.com/mysociety/alaveteli/blob/master/script/switch-theme.rb) +to set the current theme if you are working with multiple themes. This can be +useful for switching between the default `alavetelitheme` and your own fork. + +## Testing your theme + +You can add tests for the changes in functionality that are implemented +in your theme. These use <a href="http://rspec.info/">rspec</a>, as does the main Alaveteli test suite. +They should be put in the `spec` directory of your theme. They are run +separately from the main Alaveteli tests by executing the following command in the directory in which Alaveteli is installed (substituting your theme directory for `alavetelitheme`): -## Working with themes + bundle exec rspec lib/themes/alavetelitheme/spec -You can use [`script/switch-theme.rb`](https://github.com/mysociety/alaveteli/blob/master/script/switch-theme.rb) to set the current theme if you are working with multiple themes. This might be useful for switching between the default `alavetelitheme` and your own fork. +You can see some example tests in the <a href="https://github.com/mysociety/whatdotheyknow-theme/tree/master/spec">whatdotheyknow-theme</a>. diff --git a/docs/customising/translation.md b/docs/customising/translation.md index d4ccedfa7..bc0b52b6e 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -48,13 +48,13 @@ translators a chance to catch up -- read the rest of this page for details. ## Alaveteli's translations You don't need to be a programmer to translate Alaveteli -- we use an external -website called Transifex to help manage translations. This makes it easy for +website called <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> to help manage translations. This makes it easy for translators to get to work, but it does mean you (or your technical team) need to do a little extra work to get those translations back into Alaveteli when they are ready. The Transifex project is at -[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) +[https://www.transifex.com/projects/p/alaveteli](https://www.transifex.com/projects/p/alaveteli) -- you'll probably want an account there (ask on the mailing list). It has a fairly easy-to-use interface for contributing translations. @@ -161,6 +161,13 @@ This will be the job of the technical people on your team (or even mySociety's release manager). If translators aren't technical, they can use Transifex without needing to worry about this. +## The help pages + +As the help pages for Alaveteli contain lots of text, they're translated +outside Transifex, by translating each whole help page and replacing it +in the theme that Alaveteli is using, so that it overrides the default +page. See the [guide to Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for more +information on this. ## Developers and internationalisation diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md index 24c0c31e0..fb7f2930b 100644 --- a/docs/developers/i18n.md +++ b/docs/developers/i18n.md @@ -6,8 +6,9 @@ title: Internationalisation (for devs) # Internationalisation in the code <p class="lead"> - This page describes some technical aspects of internationalising the - Alaveteli code. It's mostly aimed at devs who are working on the + This page describes some technical aspects of + <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalising</a> + the Alaveteli code. It's mostly aimed at devs who are working on the codebase — if you just want to translate Alaveteli into your own language, see <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> @@ -18,8 +19,7 @@ title: Internationalisation (for devs) Deployed translations for the project live in ``locale/``. -We encourage translations to be done on -[Transifex](https://www.transifex.net/projects/p/alaveteli/) +We encourage translations to be done on <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> because translators can work through its web interface rather than needing to edit the <a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> directly. Ultimately, Transifex just captures translators' diff --git a/docs/getting_started.md b/docs/getting_started.md index eddcf78a6..3ea67c818 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -29,7 +29,7 @@ available time. You can get a feeling for how things might turn out by reading [how an Alaveteli was set up in -Spain]({{ site.baseurl }}2012/04/16/a-right-to-know-site-for-spain/) +Spain](https://www.mysociety.org/2012/04/16/a-right-to-know-site-for-spain/) (remember that this was with an experienced developer in charge). You will also need to think about how you will run the website; a successful Alaveteli requires lots of ongoing effort to moderate and publicise (see Step 6 and Step @@ -158,7 +158,7 @@ If you email possible supporters asking for help, in addition to helping make your job easier, it will also help you identify eager people who might be interested in helping you maintain and run the website. We have written [a blog post about -this]({{ site.baseurl }}2011/07/29/you-need-volunteers-to-make-your-website-work/). +this](https://www.mysociety.org/2011/07/29/you-need-volunteers-to-make-your-website-work/). The admin interface includes a page where you can upload a CSV file (that's a file containing comma-separated values) to create or edit authorities. CSV is a @@ -216,17 +216,8 @@ often less. But complicated workflows might take a bit longer. The default help pages in Alaveteli are taken from WhatDoTheyKnow, and are therefore relevant only to the UK. You should take these pages as inspiration, -but review their content with a view to your jurisdiction. The important pages -to translate are: - -* [About](https://github.com/mysociety/alaveteli/blob/master/app/views/help/about.rhtml): why the website exists, why it works, etc -* [contact](https://github.com/mysociety/alaveteli/blob/master/app/views/help/contact.rhtml): how to get in touch -* [credits](https://github.com/mysociety/alaveteli/blob/master/app/views/help/credits.rhtml): who is involved in the site. Importantly, includes a section on how users can help the project. -* [officers](https://github.com/mysociety/alaveteli/blob/master/app/views/help/officers.rhtml): information for the officers who deal with FOI at authorities. They get a link to this page in emails that the site sends them. -* [privacy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/privacy.rhtml): privacy policy, plus information making it clear that requests are going to appear on the internet. Let users know if they are allowed to use pseudonyms in your jurisdiction. -* [requesting](https://github.com/mysociety/alaveteli/blob/master/app/views/help/requesting.rhtml): the main help page about making requests. How it works, how to decide who to write to, what they can expect in terms of responses, how to make appeals, etc. -* [unhappy](https://github.com/mysociety/alaveteli/blob/master/app/views/help/unhappy.rhtml): users are taken to this page after a request that has been somehow unsuccessful (e.g. the request has been refused, or the authority is insisting on a postal request). The page should encourage them to keep going, e.g. by starting a new request or addressing it to a different body. -* [why email](https://github.com/mysociety/alaveteli/blob/master/app/views/help/_why_they_should_reply_by_email.rhtml): a snippet of information that explains why users should insist on replies by email. This is displayed next to requests that have "gone postal". +but review their content with a view to your jurisdiction. See [the documentation on Alaveteli's themes]({{ site.baseurl }}docs/customising/themes/#customising-the-help-pages) for details +on which pages are important, and what content they need to have. The help pages contain some HTML. Your tech person should be able to advise on this. @@ -285,7 +276,7 @@ spreadsheet. The help pages need to have one copy saved for each language; your tech person will put them in the right place. The web interface translations are managed and collaborated via a website -called Transifex. This website allows teams of translators to collaborate in +called <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a>. This website allows teams of translators to collaborate in one place, using a fairly easy interface. The Alaveteli page on Transifex is at @@ -347,7 +338,7 @@ This will be easier to do with a small team of people sharing jobs. Hopefully you have been lucky enough to get funding to pay people to do these tasks. However, you are also likely to have to rely on volunteers. We've written [a blog post about the importance of -volunteers]({{ site.baseurl }}2011/07/29/you-need-volunteers-to-make-your-website-work/), which you should read. +volunteers](https://www.mysociety.org/2011/07/29/you-need-volunteers-to-make-your-website-work/), which you should read. You'll need to set up a group email address for all the people who will manage the website. All site user queries will go here, as will automatic diff --git a/docs/glossary.md b/docs/glossary.md index b5239a32a..585ca67be 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -15,23 +15,30 @@ Definitions ----------- <ul class="definitions"> + <li><a href="#admin">admin interface</a></li> + <li><a href="#advanced-search">advanced search</a></li> <li><a href="#alaveteli">Alaveteli</a></li> <li><a href="#agnostic">asker agnostic</a></li> <li><a href="#authority">authority</a></li> <li><a href="#blackhole">black hole</a></li> <li><a href="#bounce-message">bounce message</a></li> <li><a href="#capistrano">Capistrano</a></li> + <li><a href="#category">category</a></li> + <li><a href="#categorisation-game">categorisation game</a></li> <li><a href="#censor-rule">censor rule</a></li> <li><a href="#development">development site</a></li> + <li><a href="#disclosure-log">disclosure log</a></li> <li><a href="#emergency">emergency user</a></li> <li><a href="#foi">freedom of information</a></li> <li><a href="#git">git</a></li> <li><a href="#holding_pen">holding pen</a></li> + <li><a href="#i18n">internationalisation</a></li> <li><a href="#newrelic">New Relic</a></li> - <li><a href="#mta">MTA</a></li> + <li><a href="#mta">Mail Transfer Agent</a></li> <li><a href="#po">.po files</a></li> <li><a href="#production">production site</a></li> <li><a href="#publish">publish</a></li> + <li><a href="#publication-scheme">publication scheme</a></li> <li><a href="#recaptcha">recaptcha</a></li> <li><a href="#redact">redacting</a></li> <li><a href="#regexp">regular expression</a></li> @@ -40,15 +47,79 @@ Definitions <li><a href="#response">response</a></li> <li><a href="#rails">Ruby on Rails</a></li> <li><a href="#sass">Sass</a></li> + <li><a href="#spam-address-list">spam address list</a></li> <li><a href="#staging">staging site</a></li> <li><a href="#state">state</a></li> + <li><a href="#super">superuser</a></li> + <li><a href="#tag">tag</a></li> <li><a href="#theme">theme</a></li> + <li><a href="#transifex">Transifex</a></li> + <li><a href="#wdtk">WhatDoTheyKnow</a></li> </ul> <dl class="glossary"> <dt> + <a name="admin">admin interface</a> (also: admin) + </dt> + <dd> + The <strong>admin interface</strong> allows users who have + <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> + administrator privilege to manage some aspects of how your + Alaveteli site runs. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + You can access your installation's <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> + at <code>/admin</code>. + </li> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + <li> + For lots more about running an Alaveteli site, see the + <a href="{{ site.baseurl }}running/admin_manual">adminstrator's guide</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="advanced-search">advanced search</a> + </dt> + <dd> + Alaveteli's <strong>advanced search</strong> lets users search using + more complex criteria than just words. This includes Boolean operators, + date ranges, and specific indexes such as <code>status:</code>, + <code>requested_by:</code>, <code>status:</code> and so on. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + Advanced search is available on your Alaveteli site at + <code>/advancedsearch</code>. That page shows suggestions and examples + of the searches that are supported. + </li> + <li> + For more about constructing complex queries, see + <a href="http://xapian.org/docs/queryparser.html">Xapian + search parser</a>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="alaveteli">Alaveteli</a> </dt> <dd> @@ -57,7 +128,7 @@ Definitions managing and archiving Freedom of Information requests. <p> It grew from the successful FOI UK project - <a href="https://www.whatdotheyknow.com">WhatDoTheyKnow</a>. + <a href="#wdtk" class="glossary__link">WhatDoTheyKnow</a>. We use the name <em>Alaveteli</em> to distinguish the software that runs the platform from any specific website that it is powering. </p> @@ -108,7 +179,8 @@ Definitions <p>More information:</p> <ul> <li> - An administrator can add, edit, or remove authorities in the admin + An <a href="#super" class="glossary__link">administrator</a> + can add, edit, or remove authorities in the admin. </li> <li> Authorities are usually, but not always, public bodies that are obliged by the local @@ -118,6 +190,10 @@ Definitions site that are not subject to FoI law, but which have either voluntarily submitted themselves to it, or which we believe should be accountable in this way. </li> + <li> + You can organise your authorities using + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a>. + </li> </ul> </div> </dd> @@ -188,6 +264,41 @@ Definitions </dd> <dt> + <a name="category">category</a> + </dt> + <dd> + You can arrange your <a href="#authority" class="glossary__link">authorities</a> + into <strong>categories</strong> so that they are easier for your users + to find. For example, you might put all different schools into the + "School" category, and universities into "Universities". You can also + group categories under headings (such as "Education"). + <p> + These categories and headings appear on the list of public authorities that + is displayed on your site. + </p> + <p> + Use <a href="#tag" class="glossary__link">tags</a> to associate + authorities with specific categories. + </p> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> +</dd> + <dt> + <a name="categorisation-game">categorisation game</a> + </dt> + <dd> + The categorisation game is a way that users of an Alaveteli site can help the site stay current and accurate by updating the status of old requests where the original requester has never said whether the authority responded with the information or not. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + the categorisation game on the <a href="http://demo.alaveteli.org/categorise/play">demo Alaveteli site</a>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="censor-rule">censor rule</a> </dt> <dd> @@ -232,6 +343,26 @@ Definitions </dd> <dt> + <a name="disclosure-log">disclosure log</a> + </dt> + <dd> + Some <a href="#authority" class="glossary__link">authorities</a> routinely + publish their responses to <a href="#foi" class="glossary__link">Freedom of + Information</a> requests online. This collection of responses is called a + <strong>disclosure log</strong>, and if an authority has such a log on its + website, you can add the URL so Alaveteli can link to it. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + You can add a disclosure log URL by + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. + </li> + </ul> + </div> + </dd> + + <dt> <a name="emergency">emergency user</a> </dt> <dd> @@ -249,7 +380,7 @@ Definitions <li> The username and password are defined by the configuration settings <code><a href="{{site.baseurl}}docs/customising/config/#admin_username">ADMIN_USERNAME</a></code> - and + and <code><a href="{{site.baseurl}}docs/customising/config/#admin_password">ADMIN_PASSWORD</a></code>. </li> <li> @@ -266,7 +397,7 @@ Definitions </dd> <dt> - <a name="foi">Freedom of Information</a> (also FOI) + <a name="foi">Freedom of Information</a> (also: FOI) </dt> <dd> <strong>Freedom of information</strong> laws allow access by the general public @@ -287,7 +418,7 @@ Definitions </dd> <dt> - <a name="git">git</a> (also github, git repository, and git repo) + <a name="git">git</a> (also: github, git repository, and git repo) </dt> <dd> We use a popular source code control system called <strong>git</strong>. This @@ -328,24 +459,79 @@ Definitions <a name="holding_pen">holding pen</a> </dt> <dd> - The <strong>holding pen</strong> is the conceptual place where responses that - could not be delivered are held. They need attention from a administrator. + The <strong>holding pen</strong> is the conceptual place where responses + that could not be delivered are held. They need attention from an + <a href="#super" class="glossary__link">administrator</a>. + <p> + In fact, the holding pen is really a special "sticky" <a href="#request" + class="glossary__link">request</a> that only exists to accept unmatched + responses. Whenever Alaveteli receives an email but can't work out which + request it is a response to, it attaches it to the holding pen instead. + </p> <div class="more-info"> <p>More information:</p> <ul> <li> - see the <a href="{{ site.baseurl }}docs/running/admin_manual/">admin manual</a> for - information on dealing with emails in the holding pen + See more <a href="{{ site.baseurl }}docs/running/holding_pen">about + the holding pen</a>, including why messages end up there, and + instructions on what to do with them. + </li> + <li> + The most common reason for a response to be in the holding pen is that + an <a href="#authority" class="glossary__link">authority</a> replied + to a request with the wrong email address (for example, by copying + the email address incorrectly). </li> </ul> </div> </dd> <dt> - <a name="mta">MTA</a> (Mail Transfer Agent) + <a name="i18n">internationalisation</a> (also: i18n) </dt> <dd> - A <strong>Mail Tranfer Agent</strong> is the the program which actually sends + <strong>Internationalisation</strong> is the way Alaveteli adapts the + way it presents text based on the language or languages that your website + supports. It's sometimes abbreviated as <em>i18n</em> (because there are + 18 letters between i and n). + <p> + Often you don't need to worry about the details of how this is done + because once you've configured your site's + <code><a href="{{ site.baseurl }}docs/customising/config/#default_locale">DEFAULT_LOCALE</a></code> + Alaveteli takes care of it for you. + But when you do need to work on i18n (for example, if you're customising + your site by + <a href="{{ site.baseurl }}docs/customising/translation/">translating</a> it, or + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">uploading names</a> + of the public bodies in more than one language) at the very least you may + need to know the language codes you're site is using. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about <a href="{{ site.baseurl }}docs/developers/i18n/">internationalising Alaveteli</a> + </li> + <li> + See mySociety's + <a href="http://mysociety.github.io/internationalization.html">i18n guidelines</a> for developers + </li> + <li> + <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">List of language codes</a> + </li> + <li> + For more about i18n in software generally, see + the <a href="http://en.wikipedia.org/wiki/Internationalization_and_localization">i18n Wikipedia article</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="mta">Mail Transfer Agent</a> (MTA) + </dt> + <dd> + A <strong>Mail Transfer Agent</strong> is the the program which actually sends and receives email. Alaveteli sends email on behalf of its users, and processes the <a href="#response" class="glossary__link">responses</a> and replies it receives. All this email goes through the MTA, which is a seperate service on your system. @@ -392,12 +578,13 @@ Definitions <a name="po"><code>.po</code> file</a> (and <code>.pot</code> file) </dt> <dd> - These are the files needed by the gettext mechanism Alaveteli uses for - localisation. A <code>.pot</code> file is effectively a list of all the - strings in the application that need translating. Each <code>.po</code> - file contains the mapping between those strings, used as keys, and their - translations for one particular language. The key is called the - <em>msgid</em>, and its corresponding translation is the <em>msgstr</em>. + These are the files needed by the <code>gettext</code> mechanism Alaveteli + uses for localisation. A <code>.pot</code> file is effectively a list of + all the strings in the application that need translating. Each + <code>.po</code> file contains the mapping between those strings, used as + keys, and their translations for one particular language. The key is called + the <em>msgid</em>, and its corresponding translation is the + <em>msgstr</em>. <div class="more-info"> <p>More information:</p> <ul> @@ -410,10 +597,15 @@ Definitions Alaveteli</a> for more technical details. </li> <li> - Alaveteli is on the <a href="https://www.transifex.net/projects/p/alaveteli/">Transifex</a> + Alaveteli is on the <a href="https://www.transifex.com/projects/p/alaveteli/">Transifex</a> website, which lets translators work on Alaveteli in a browser, without needing to worry about this underlying structure. </li> + <li> + See more about the + <a href="https://www.gnu.org/software/gettext/"><code>gettext</code> + system</a>. + </li> </ul> </div> </dd> @@ -464,6 +656,29 @@ Definitions </dd> <dt> + <a name="publication-scheme">publication scheme</a> + </dt> + <dd> + Some <a href="#authority" class="glossary__link">authorities</a> have a + <strong>publication scheme</strong> which makes it clear what information + is readily available from them under <a href="#foi" + class="glossary__link">Freedom of Information</a> law, and how people can + get it. This may be a requirement for their compliance with the law, or it + may simply be good practice. If an authority has published such a scheme on + its website, you can add the URL so Alaveteli can link to it. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + You can add a publication scheme URL by + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">updating authority data</a> in the admin. + </li> + </ul> + </div> + </dd> + + + <dt> <a name="recaptcha">recaptcha</a> </dt> <dd> @@ -583,7 +798,7 @@ Definitions </li> <li> We try to coordinate releases with any active translation work too. - See <a href="http://localhost:4000/docs/customising/translation/">translating + See <a href="{{ site.baseurl }}docs/customising/translation/">translating Alaveteli</a> for more information. </li> <li> @@ -617,7 +832,7 @@ Definitions </dd> <dt> - <a name="rails">Ruby on Rails</a> (also Rails) + <a name="rails">Ruby on Rails</a> (also: Rails) </dt> <dd> Alaveteli is written in the Ruby programming language, using @@ -663,6 +878,33 @@ Definitions </dd> <dt> + <a name="spam-address-list">spam address list</a> + </dt> + <dd> + Alaveteli maintains a <strong>spam address list</strong>. Any incoming message to an email + address on that list will be rejected and won't appear in the admin. + <p> + This is mainly for email addresses whose messages are ending up + in the <a href="#holding_pen" class="glossary__link">holding pen</a>, because + those are typically addresses that can be safely ignored as they do not + relate to an active <a href="#request" class="glossary__link">request</a>. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + To add addresses to the spam address list , see + <a href="{{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting + spam that arrives in the holding pen</a>. + </li> + <li> + The spam address list is available on your site at <code>/admin/spam_addresses</code>. + </li> + </ul> + </div> + </dd> + + <dt> <a name="staging">staging server</a> (also: staging site) </dt> <dd> @@ -721,6 +963,62 @@ Definitions </dd> <dt> + <a name="super">superuser</a> (also: super privilege, administrator) + </dt> + <dd> + A <strong>superuser</strong>, or <strong>administrator</strong>, is an + Alaveteli user who has been granted the privilege to use all features of the + <a href="{{ site.baseurl }}docs/glossary/#admin" + class="glossary__link">admin interface</a>. + <p> + The only way to access the admin without being an Alaveteli superuser + is as the <a href="{{ site.baseurl }}docs/glossary/#emergency" + class="glossary__link">emergency user</a>, which should be disabled in + normal operation. + </p> + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + To grant a user admin privilege, log into the admin and change + their <em>Admin level</em> to "super" (or revoke the privilege + by changing it to "none"). + </li> + <li> + On a newly-installed Alaveteli system, you can grant yourself + admin privilege by using the + <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency + user</a>. + </li> + </ul> + </div> + </dd> + + <dt> + <a name="tag">tag</a> + </dt> + <dd> + A <strong>tag</strong> is a keyword added to an + <a href="#authority" class="glossary__link">authority</a>. Tags + are searchable, so can be useful to help users find authorities based + by topic or even unique data (for example, in the + <a href="#wdtk" class="glossary__link">WhatDoTheyKnow</a> we tag every + registered charity with its official charity number). You can also use + tags to assign authorities to + <a href="#category" class="glossary__link">categories</a>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + More about + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">categories and tags</a> + </li> + </ul> + </div> + </dd> + + + <dt> <a name="theme">theme</a> </dt> <dd> @@ -728,11 +1026,49 @@ Definitions and the code that causes the site to look or behave differently from the default. Typically you'll need a theme to make Alaveteli show your own brand. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + <a href="{{ site.baseurl }}docs/customising/themes/">about themes</a> + </li> + </ul> + </div> + </dd> + <dt> + + <a name="transifex">Transifex</a> + </dt> + <dd> + + <a href="https://www.transifex.com/">Transifex</a> is a website that helps translators add translations for software projects. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + The Transifex project for Alaveteli is at <a href="https://www.transifex.com/projects/p/alaveteli">https://www.transifex.com/projects/p/alaveteli</a> + </li> + </ul> + </div> + </dd> + + + <dt> + <a name="wdtk">WhatDoTheyKnow</a> + </dt> + <dd> + The website <strong>WhatDoTheyKnow</strong>.com is the UK installation of + Alaveteli, run by <a href="http://mysociety.org">mySociety</a>. + <p> + In fact, WhatDoTheyKnow predates Alaveteli because the site started in + 2008, and was the foundation of the redeployable, customisable + Alaveteli plattorm released in 2011. + </p> <div class="more-info"> <p>More information:</p> <ul> <li> - <a href="{{ site.baseurl }}docs/customising/themes/">about themes</a> + <a href="http://www.whatdotheyknow.com">WhatDoTheyKnow.com</a> </li> </ul> </div> diff --git a/docs/installing/deploy.md b/docs/installing/deploy.md index a0a4c0abb..355c4f8a2 100644 --- a/docs/installing/deploy.md +++ b/docs/installing/deploy.md @@ -175,7 +175,7 @@ for the config that you've set up). Ensure you've got a `config/deploy.yml` file with the correct settings for your site. If there are other people in your team who need to deploy, you'll need to share it with them too -- it might be a good idea to keep the latest -version in a [Gist](http://gist.github.com/). +version in a private [Gist](http://gist.github.com/). * to deploy to staging, just run `cap deploy` * to deploy to production, run `cap -S stage=production deploy` diff --git a/docs/installing/macos.md b/docs/installing/macos.md index e93ea452f..2c08be0e5 100644 --- a/docs/installing/macos.md +++ b/docs/installing/macos.md @@ -71,7 +71,7 @@ Read `rvm notes` and `rvm requirements` carefully for further instructions. Then The `mahoro` and `pg` gems require special installation commands. Rubygems must be downgraded to 1.6.2 to avoid deprecation warnings when running tests. rvm 1.8.7 - gem update --system 1.6.2 + gem update --system 2.1.11 gem install mahoro -- --with-ldflags="-L/usr/local/Cellar/libmagic/5.09/lib" --with-cppflags="-I/usr/local/Cellar/libmagic/5.09/include" env ARCHFLAGS="-arch x86_64" gem install pg @@ -96,8 +96,9 @@ Create a `foi` user from the command line, like this: createuser -s -P foi -_Note:_ Leaving the password blank will cause great confusion if you're new to -PostgreSQL. +_Note:_ After running this command you will be prompted to set a +password for the user. Don't leave it blank if you are new to +PostgreSQL, or it could be difficult to set later for you. We'll create a template for our Alaveteli databases: @@ -112,18 +113,11 @@ Then create the databases: ### Clone Alaveteli -We don't want to vendor Rails, as it causes problems locally. - git clone https://github.com/mysociety/alaveteli.git cd alaveteli git submodule init - - sed -i~ 's/\\[submodule "vendor\/rails"\\]//' .git/config - - sed -i~ 's/url = git:\/\/github.com\/rails\/rails.git//' .git/config git submodule update -**Note:** Due to Markdown bugs, the first `sed` command above does not display properly if it appears in blockquote. ### Configure Alaveteli diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index 8c9e2a8d6..9cad6b5b9 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -351,7 +351,12 @@ Example `development` section of `config/database.yml`: Make sure that the user specified in `database.yml` exists, and has full permissions on these databases. -As the user needs the ability to turn off constraints whilst running the tests they also need to be a superuser. If you don't want your database user to be a superuser, you can add this line to the `test` section in `database.yml` (as seen in `config/database.yml-example`): +As the user needs the ability to turn off constraints whilst running the tests +they also need to be a superuser (clarification: a <em>Postgres</em> superuser, +not an Alaveteli +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">superuser</a>). +If you don't want your database user to be a superuser, you can add this line +to the `test` section in `database.yml` (as seen in `config/database.yml-example`): constraint_disabling: false diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md index d5c4675f0..2c6e84e1b 100644 --- a/docs/installing/next_steps.md +++ b/docs/installing/next_steps.md @@ -8,13 +8,22 @@ title: Next Steps OK, you've installed a copy of Alaveteli, and can see the site in a browser. What next? </p> + * [Create a superuser admin account](#create-a-superuser-admin-account) + * [Load sample data](#load-sample-data) + * [Test out the request process](#test-out-the-request-process) + * [Import Public Authorities](#import-public-authorities) + + + ## Create a superuser admin account Alaveteli ships with an <a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a> that has access to the admin. So when you've just created a new site, you should sign up to create your own account, then log into admin as the emergency -user to promote your new account to be an administrator with *super* privileges. +user to promote your new account to be an administrator with +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a> +privilege. As soon as that's done, disable the emergency user, because you don't need to use it any more: you've superseded it with your new admin account. @@ -116,7 +125,8 @@ follow the steps described in the previous section. Alaveteli can import a list of public authorities and their contact email addresses from a CSV file. -You can find the uploader in under the "Authorities" tab of the admin section, or go straight to `/admin/body/import_csv`. +Follow the instructions for +[uploading public authority data]({{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data). ## Set the amount of time authorities will be given to respond to requests diff --git a/docs/installing/vagrant.md b/docs/installing/vagrant.md index 8938d496b..a0b058da5 100644 --- a/docs/installing/vagrant.md +++ b/docs/installing/vagrant.md @@ -5,35 +5,38 @@ title: Vagrant # Alaveteli using Vagrant <p class="lead"> -Vagrant provides an easy method to set up virtual development environments; for -further information see <a href="http://www.vagrantup.com">the Vagrant website</a>. -We bundle an example Vagrantfile in the repository, which runs the -<a href="{{ site.baseurl }}docs/installing/script/">install script</a> for you. + <a href="https://www.vagrantup.com">Vagrant</a> provides an easy method to set + up virtual development environments We bundle an example Vagrantfile in the + repository, which runs the + <a href="{{ site.baseurl}}docs/installing/script/">install script</a> for you. </p> Note that this is just one of [several ways to install Alaveteli]({{ site.baseurl }}docs/installing/). The included steps will use vagrant to create a development environment -where you can run the test suite, the development server and make +where you can run the test suite and the development server, and make changes to the codebase. -The basic process is to create a base virtual machine, and then +The basic process is to create a base virtual machine (VM), and then provision it with the software packages and setup needed. The supplied scripts will create you a Vagrant VM based on the server edition of Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. -1. Get a copy of Alaveteli from GitHub and create the Vagrant instance. - This will provision the system and can take some time - usually at - least 20 minutes. +1. Get a copy of Alaveteli from + <a href="{{ site.baseurl }}docs/glossary/#git" class="glossary__link">GitHub</a>: # on your machine $ git clone git@github.com:mysociety/alaveteli.git $ cd alaveteli $ git submodule update --init + +2. Create the Vagrant VM. This will provision the system and can take some time + — sometimes as long as 20 minutes. + $ vagrant --no-color up -2. You should now be able to ssh in to the Vagrant guest OS and run the - test suite: +3. You should now be able to log in to the Vagrant guest OS with `ssh` and run + the test suite: $ vagrant ssh @@ -42,12 +45,34 @@ Ubuntu 12.04 LTS that contains everything you need to work on Alaveteli. $ bundle exec rake spec -3. Run the rails server and visit the application in your host browser - at http://10.10.10.30:3000 +4. Run the rails server: # in the virtual machine terminal bundle exec rails server +You can now visit the application in your browser (on the same machine that is +running Vagrant) at `http://10.10.10.30:3000`. + +If you need to stop the server, simply press **Ctl-C** within that shell. + +It's also possible to stop the server from a different terminal shell in the +Vagrant VM. Log in, find the process ID for the Alaveteli server (in the example +below, this is `1234`), and issue the `kill` command: + + $ vagrant ssh + + # now in a terminal on the virtual machine + $ cat /home/vagrant/alaveteli/tmp/pids/server.pid + 1234 + $ kill -2 1234 + +Alternatively, you can shut down the whole VM without deleting it with the +command <code>vagrant halt</code> +on the host command line. To start it up again, go to step 2, above — it +won't take so long this time, because the files are already in place. +See [the Vagrant documentation](https://docs.vagrantup.com/v2/) +for full instructions on using Vagrant. + ## What next? Check out the [next steps]({{ site.baseurl }}docs/installing/next_steps/). diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index d166cb859..7c112400c 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -31,10 +31,14 @@ In this guide: <ul> <li><a href="#administrator-privileges-and-accessing-the-admin-interface">Administrator privileges and accessing the admin interface</a></li> <li><a href="#removing-a-message-from-the-holding-pen">Removing a message from the 'Holding Pen'</a></li> - <li><a href="#editing-and-uploading-public-body-email-addresses">Editing and uploading public body email addresses</a></li> + <li><a href="#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting spam that arrives in the holding pen</a></li> + <li><a href="#creating-changing-and-uploading-public-authority-data">Creating, changing and uploading public authority data</a></li> <li><a href="#banning-a-user">Banning a user</a></li> - <li><a href="#deleting-a-request">Deleting a request</a></li> + <li><a href="#allowing-a-user-to-make-more-requests">Allowing a user to make more requests</a></li> + <li><a href="#batch-requests">Batch requests</a></li> + <li><a href="#resending-a-request-or-sending-it-to-a-different-authority">Resending a request or sending it to a different authority</a></li> <li><a href="#hiding-a-request">Hiding a request</a></li> + <li><a href="#deleting-a-request">Deleting a request</a></li> <li><a href="#hiding-an-incoming-or-outgoing-message">Hiding an incoming or outgoing message</a></li> <li><a href="#editing-an-outgoing-message">Editing an outgoing message</a></li> <li><a href="#hiding-certain-text-from-a-request-using-censor-rules">Hiding certain text from a request</a></li> @@ -308,79 +312,456 @@ line, and piping the contents of that file into the mail handling script. e.g. ### Administrator privileges and accessing the admin interface -The administrative interface is at the URL `/admin`. +The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a> +is at the URL `/admin`. Only users who are +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrators</a> +can access the admin interface. + +To make a user an administrator on a brand new site, +[follow these steps]({{ site.baseurl }}docs/installing/next_steps/#create-a-superuser-admin-account). + +If you're already an administrator, you can grant other users administrator +privilege too. Go to `/admin/users` or click on **Users** at the top of +the admin. Find the user in the list, and click on the name to see the user +details. On that page, click **Edit**. Change the *Admin level* to “super” and +click **Save**. + +As well having access to the admin interface, users who are administrators also +have extra privileges in the main website front end. Administrators can: + + * categorise any request + * view items that have been hidden from the search + * follow "admin" links that appear next to individual requests and comments + +<div class="attention-box warning"> + It is possible completely to override the administrator authentication by + setting + <code><a href="{{ site.baseurl }}docs/customising/config/#skip_admin_auth">SKIP_ADMIN_AUTH</a></code> + to <code>true</code> in <code>general.yml</code>. Never do this, unless you + are working on a <a href="{{ site.baseurl }}docs/glossary/#development" + class="glossary__link">development</a> server. +</div> + +### Removing a message from the holding pen + +Alaveteli puts incoming messages (that is, +<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">responses</a>) +into the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> +if their `To:` email addresses can't automatically be associated with a +<a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">request</a>. + +The two most common reasons for this are: + + * the request has closed + * the email address was wrongly spelled (for example, the sender missed the last + character off the email address when they copied it) + +When this happens, the messages wait in the holding pen until an administrator +redelivers them to the correct request, or else deletes them. + +To do this, log into the +The <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a> +at `/admin`. If there are any messages in the holding pen, you'll see this +message under the title *Things to do*: + +> Put misdelivered responses with the right request + +Click on that message — you'll see a list of all the messages that need +your attention. Click on any one of them to see the details. + +<div class="attention-box helpful-hint"> + If the message does not belong to any request, you can delete it instead. + Simply click on the <strong>Destroy Message</strong> button instead of + redelivering it. +</div> + +When you inspect a message, you may see a guess made by Alaveteli as to which +request the message belongs to. Check this request. If the guess is right +— the incoming email really is a response to that request — +the request's *title_url* will already be in the input box: click the +**Redeliver to another request** button. + +If there is not a guess, or Alaveteli's guess is wrong, look at the `To:` +address of the raw email and the contents of the message itself. You need +to figure out which request it belongs to. You can browse and search +requests in the admin interface by clicking **Requests** at the top of the +admin. When you have found the correct request, copy either its *id* or +its *url_title*. + +<div class="attention-box info"> + <p><strong>How to find a request's <em>id</em> or <em>url_title</em></strong></p> + <p> + A request's <em>id</em> is the number after <code>/show/</code> in the + admin interface's URL when you are looking at that request. + For example, if the URL is <code>/admin/request/show/118</code>, then the + <em>id</em> is <code>118</code>. + </p> + <p> + A request's <em>url_title</em> is the part after <code>/request/</code> + in your Alaveteli site's URL when you are looking at that request. + In the URL <code>/request/how_many_vehicles</code>, the + <em>url_title</em> is <code>how_many_vehicles</code>. + </p> +</div> + +Once you have identified the request the message belongs to, return to the +holding pen message page. Find the incoming message's "Actions" and paste the +request *id* or *url_title* into the text input. Click on the **Redeliver to +another request** button. + +The message will now be associated with the correct request. It is no longer +in the holding pen, and is shown instead on the public request page. + + +### Rejecting spam that arrives in the holding pen + +Alaveteli maintains a +<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. +Any incoming message to an email address on that list +*that would otherwise be put in the holding pen* will be rejected and won't +appear in the admin. + +If you see spam messages in the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, +check if they are being sent to a *specific* email address. If they are, that +email address has become a "spam-target" and you should add it to the spam +address list. Thereafter, Alaveteli will automatically reject any messages that +come to that address. + +An email address that is not associated with a request (that is, one whose +messages end up in the holding pen) becomes a spam-target once it's been +harvested by spammers. There are several reasons why such an invalid address +might exist — perhaps it was mis-spelled in a manual reply, for example. +Our experience from running +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +is that you can safely dismiss incoming email to such addresses once they have +been targeted in this way. Legitimate emails that arrive in the holding pen +tend to be unique errors (for example, missing the last character of the email +address due to a cut-and-paste mistake) and the nature of the lifecycle of +requests means they don't typically get used for spam until they are +effectively dead. + +To add an email address to the spam address list you need to copy it from an +incoming message and paste it into the spam addresss list. The easiest way to +do this is to click on **Summary** at the top of any admin page, and then click +on **Put misdelivered responses with the right requests** to see the contents +of the holding pen. + +<div class="attention-box info"> + If there are no messages in the holding pen, Alaveteli won't show you this + link. Great — there are no misdelivered responses needing your + attention right now! +</div> + +Inside the holding pen, you'll see the list of emails awaiting attention +— click on an email's subject line to see the whole message and its +details. Copy the `To:` email address, then click on the **Spam Addresses** +link under *Actions*. Paste the email address into the text input and click the +**Add Spam Address** button. + +You can see the spam address list (that is, all known spam-target email +addresses) at any time by going to the admin interface at `/admin/spam_addresses`. + +You can remove any address from the list by clicking the **Remove** button +next to it. Of course, this won't restore any messages that have been +rejected, but Alaveteli will not reject any new messages that are sent to +this address. + +Note that if you are seeing consistent spam email in your holding pen, you +should also consider implementing (or increasing) the anti-spam measures +running in your +<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. + +### Creating, changing and uploading public authority data + +There are three ways to change public authority data on your site: + + * *Create* — + You can create a new public authority in the admin interface. Go to **Authorities**, and click the **New Public Authority** button. + + * *Edit* — + Once an authority is created, you can update its email address or other + details by editing it in the admin interface. Go to **Authorities**, find + the authority you want to update, and click on **edit**. + + * *Upload* — + You can also create or edit more than one authority at the same time by + uploading a file containing the data in comma-separated values (CSV) + format. This works for new authorities as well as those that already exist + on your site. Go to **Authorities** and click the **Import from CSV** button. See the rest of this section for more about uploading. + +The upload feature is useful — especially when an Alaveteli site is first +set up — because it's common to collect data such as the contact details +for the public authorities in a spreadsheet. Alaveteli's upload feature makes it +easy to initially load this data onto the site. It also lets you update the +data if it changes after it's already been loaded. + +To use the data in the spreadsheet to update the bodies on your site, export +("save as") the spreadsheet as a CSV file. This is the file you can upload. + +The first line of your CSV file should start with `#` (this indicates that this +line does not contain data) and must list the column names for the data that +follows on the subsequent lines. Column names must: + + * be on the first line + * match expected names *exactly*, and include `name` and `request_email` + (see table below) + * appear in the same order as corresponding items in the lines of data that follow + +Most spreadsheet programs will produce a suitable CSV file for you, provided +that you carefully specify correct titles at the top of each column. Be sure to +use names exactly as shown — if Alaveteli encounters an +unrecognised column name, the import will fail. + +<table class="table"> + <tr> + <th>column name</th> + <th>i18n suffix?</th> + <th>notes</th> + </tr> + <tr> + <td><code>name</code></td> + <td><em>yes</em></td> + <td> + <em>This column <strong>must</strong> be present.</em><br> + The full name of the authority.<br> + If it matches an existing authority's name, that authority will be + updated — otherwise, this will be added as a new authority. + </td> + </tr> + <tr> + <td><code>request_email</code></td> + <td><em>yes</em></td> + <td> + <em>This column <strong>must</strong> be present, + but can be left empty.</em><br> + The email to which requests are sent + </td> + </tr> + <tr> + <td><code>short_name</code></td> + <td><em>yes</em></td> + <td>Some authorities are known by a shorter name</td> + </tr> + <tr> + <td><code>notes</code></td> + <td><em>yes</em></td> + <td>Notes, displayed publicly (may contain HTML)</td> + </tr> + <tr> + <td><code>publication_scheme</code></td> + <td><em>yes</em></td> + <td> + The URL of the authority's + <a href="{{ site.baseurl }}docs/glossary/#publication-scheme" class="glossary__link">publication scheme</a>, + if they have one + </td> + </tr> + <tr> + <td><code>disclosure_log</code></td> + <td><em>yes</em></td> + <td> + The URL of the authority's + <a href="{{ site.baseurl }}docs/glossary/#disclosure-log" class="glossary__link">disclosure log</a>, + if they have one + </td> + </tr> + <tr> + <td><code>home_page</code></td> + <td>no</td> + <td>The URL of the authority's home page</td> + </tr> + <tr> + <td><code>tag_string</code></td> + <td>no</td> + <td>separated tags with spaces</td> + </tr> +</table> + + * Existing authorities cannot be renamed by uploading: if you need to do + this, use the admin interface to edit the existing record first, and + change its name in the web interface. + * If the authority already exists (the `name` matches an existing authority's + name exactly), a blank entry leaves the existing value for that column + unchanged — that is, that item of data on your site will not be + changed. This means you only really need to include data you want to + update. + * Columns with "i18n suffix" can accept + <a href="{{ site.baseurl }}docs/glossary/#i18n" class="glossary__link">internationalised</a> + names. Add a full stop followed by the language code, for example: + `name.es` for Spanish (`es`). This *must* be a locale you've declared in + [`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + If you don't specify an i18n suffix, the default language for your site is + assumed. + * You can specify a blank entry in the CSV file by having no character + between commas. + * If an entry contains a comma, enclose it in double quotes like this: + `"Comma, Inc"`. + * If an entry contains any double quotes, you must replace each of + them with two (so `"` becomes `""`) and also enclose the whole entry in + double quotes like this: `"In ""quotes"""` (which will be imported as `In + "quotes"`). + +For example, here's data for three authorities in CSV format ready for upload. +The first line defines the column names, then the next three lines contain the +data (one line for each authority): + + #name,short_name,short_name.es,request_email,notes + XYZ Library Inc.,XYZ Library,XYX Biblioteca,info@xyz.example.com, + Ejemplo Town Council,,Ayuntamiento de Ejemplo,etc@example.com,Lorem ipsum. + "Comma, Inc.",Comma,,comma@example.com,"e.g. <a href=""x"">link</a>" + +Note that, if Ejemplo Town Council already exists on the site, the blank entry +for `short_name` will leave the existing value for that column unchanged. + +To upload a CSV file, log into the admin and click on **Authorities**. Click on +**Import from CSV file**, and choose the file you've prepared. + +Specify **What to do with existing tags?** with one of these options: + + * *Replace existing tags with new ones* <br/> + For each authority being updated, all existing tags will be removed, and + replaced with the ones in your CSV file. + + * *Add new tags to existing ones* <br/> + Existing tags will be left unchanged, and the tags in your CSV file will + be added to them. + +You can add a **Tag to add entries to / alter entries for**. This tag will +be applied to every body that is imported from your CSV file. + +We always recommend you click **Dry run** first -- this will run through the +file and report the changes it will make in the database, *without actually +changing the data*. Check the report: it shows what changes would be made if +you really uploaded this data, followed by a message like this: + + Dry run was successful, real run would do as above. + +If you see nothing above that line, it means the dry run has resulted in no +proposed changes. + +If everything was OK when you ran the dry run, click **Upload** instead. This +will repeat the process, but this time it will make the changes to your +site's database. + +If you see an error like `invalid email`, either you really have mistyped an +email address, or (more likely) your CSV file does not have a `request_email` +column. + +#### Creating a spreadsheet of existing authorities + +You can easily create a spreadsheet containing the authorities that <em>already +exist</em> on your site. Combined with the upload feature described above, this +may be a more convenient way to update your data than editing it in the admin +interface. + +To export the existing authorities' data, go to your site's home page (not the +admin) and click <strong>View Authorities</strong>. Then click <strong>List of +all authorities (CSV)</strong> to get a CSV file. You can then make changes to +this file using a spreadsheet program and upload it as described above. + +You'll need to remove some columns that are not accepted by the import feature +and possibly rename some that are — see the column names above. +Also, note that by default the exported spreadsheet does not contain a +`request_email` column. If you want to update email addresses, you should +manually add a column to your spreadsheet with the heading `request_email` and +fill in a new email address for each authority you want to update. Authorities +with blank values in any column will keep their existing value for that +attribute. + +<div class="attention-box info"> +Alaveteli never includes authorities which have the tag <code>site_administration</code> when it exports authorities in CSV format. +If you're running a development server with the sample data, the single example +body called "Internal admin authority" has this tag, so if you click +<strong>List of all authorities (CSV)</strong>, you'll get a CSV file which +contains no data. You need to add your own authorities (without the +<code>site_administration</code> tag) before you can export them. +</div> -Only users with the `super` admin level can access the admin interface. Users -create their own accounts in the usual way, and then administrators can give -them `super` privileges. +### Banning a user -There is an emergency user account which can be accessed via -`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and -`ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the -first `super` level accounts, you will need to log in as the emergency -user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. +You may wish to completely ban a user from the website (such as a spammer or troll for example). You need to log into the admin interface at `/admin`. On the top row of links, locate and click on ‘Users’. -Users with the superuser role also have extra privileges in the website -front end, such as being able to categorise any request, being able to view -items that have been hidden from the search, and being presented with "admin" -links next to individual requests and comments in the front end. +Find the user you wish to ban on the list and click on their name. Once on the user page, select ‘edit’. -It is possible completely to override the administrator authentication by -setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`. +Enter some text in the in the ‘Ban text’ box to explain why they have been banned. Please be aware, this is publicly viewable from the users' account. Then click on save and the user will be banned. -### Removing a message from the 'Holding Pen' +### Allowing a user to make more requests -The reason a message is in the holding pen is because the email can't be automatically associated with the request it is responding to. The email needs to be moved from the holding pen to the request it belongs with. +Alaveteli has a config setting <code><a href="{{ site.baseurl }}docs/customising/config/#max_requests_per_user_per_day">MAX_REQUESTS_PER_USER_PER_DAY</a></code>, +which determines the maximum number of requests that a normal user can +make in a day. If they try to make more than this number of requests +within a 24 hour period, they will see a message telling them that they +have hit the limit, and encouraging them to use the contact form if they +feel they have a good reason to ask for the request limit to be lifted. -First, log into the admin interface at `/admin`. You will see messages that are in the 'holding pen' under the title ‘Put misdelivered responses with the right request’. Click on the chevron to see the individual messages. +To lift the request limit for a particular user, go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin +interface</a>, click on **Users**, then click on the name of the user +you want to lift the request limit for. Click the **Edit** button. Tick +the checkbox **No rate limit**, and click the **Save** button. -If you click on a message in the holding pen, you may see a guess made by Alaveteli as to which request the message belongs to. Check this request. If it isn't the right one, or if Alaveteli hasn't made any guesses, you will need to look at the `To:` address of the raw email and the contents of the mail in order to figure out which request it belongs to. You can browse and search requests in the admin interface under the 'Requests' menu item. +### Batch requests -Once you have identified the request the message belongs to, you need to go back to the holding pen message page. Paste the request `id` or `url_title` into the box under 'Actions' in 'Incoming Message'. The request `id` can be found in the request URL in the admin interface - it is the part after `/show/`. In the admin request URL `/admin/request/show/118`, the request `id` is `118`. The `url_title` can be found in the request URL in the main interface - it is the part after `/request/`. In the URL `/request/documents_relating_to_meeting`, it is `documents_relating_to_meeting`. Then click on 'Redeliver to another request'. +Sometimes a user may want to send the same request to more than one authority, which we call a batch request. By default, Alaveteli does not allow users to make batch requests. -The message will now be associated with the correct request and will appear on the public request page. +<div class="attention-box info"> +<p>We believe that batch requests can be abused — users can send poorly thought-out or vexatious requests, which will annoy authorities and damage the reputation of your site. However, well thought-out batch requests can be an extremely useful tool in collecting comparative data sets across types of authority, for example, all police forces.</p> +<p> +We recommend that you enable batch requesting for users who you notice making the same good request to multiple authorities. +</p> +<p> +Users can choose which authorities to include in a batch requests. They can even send a request to <em>every single authority</em> on your site. Only give this power to users that you trust. +</p> +</div> -### Editing and uploading public body email addresses +To enable batch requests on your site, first you must set +<code><a href="{{ site.baseurl }}docs/customising/config/#allow_batch_requests">ALLOW_BATCH_REQUESTS</a></code> +to <code>true</code> in <code>general.yml</code>. +This does not allow anyone to make batch requests yet. You must still +enable this for each user on an individual basis. To do this, go to the +<a href="{{ site.baseurl }}docs/glossary/#admin" +class="glossary__link">admin interface</a>, click on **Users**, then +click on the name of the user who wants to make batch requests. Click +the **Edit** button. Tick the checkbox **Can make batch requests**, and +click the **Save** button. +If you've enabled batch requests for a user, when they start to make a +request, in addition to the box where they can select an authority, they +will see a link to "make a batch request". When the request is sent, +Alaveteli will make a request page for this request for each authority, +as if the user had made individual requests. -### Banning a user +### Resending a request or sending it to a different authority -You may wish to completely ban a user from the website (such as a spammer or troll for example). You need to log into the admin interface at `/admin`. On the top row of links, locate and click on ‘Users’. +If you have corrected the email address for an authority, you can resend +an existing request to that authority to the new email address. Alternatively, +a user may send a request to the wrong authority. In that situation, you can +change the authority on the request and then resend it to the correct authority. +For instructions, see +[resending a request or sending it to a different authority]({{ site.baseurl }}docs/running/requests/#resending-a-request-or-sending-it-to-a-different-authority). -Find the user you wish to ban on the list and click on their name. Once on the user page, select ‘edit’. -Enter some text in the in the ‘Ban text’ box to explain why they have been banned. Please be aware, this is publicly viewable from the users' account. Then click on save and the user will be banned. +### Hiding a request -### Deleting a request +If a request contains vexatious or inappropriate content, is libellous, or is +not a valid +<a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> +request at all, you may want to hide it. A hidden request is still visible to +you and the other administrators, and (optionally) the requester themselves. +For instructions, see +[hiding a request]({{ site.baseurl }}docs/running/requests/#hiding-a-request). -You can delete a request entirely using the admin interface. You will mainly only need to do this if someone has posted private information. Go to the admin page for the request by searching or browsing in the 'Requests' section of the admin interface. In the first section, click the 'Edit metadata' button. At the bottom of the next page, click the red 'Destroy request entirely' button. +Responses to a hidden request will be accepted in the normal way, but because +they are added to the request's page, they too will be hidden. -### Hiding a request +### Deleting a request -You can hide an entire request from the admin interface. Log in to the -admin interface at `/admin`. On the top row of links, locate and click on -'Requests'. Search or browse to find the admin page for the request you -want to hide. You can also go directly to this page by following an -'admin' link from the public request page. You can hide a request in one -of two ways. - - * <strong>Hiding a vexatious or non-FOI request and notifying the - requester</strong> - Scroll down to the 'actions' section of the request - admin page. Select one of the options next to 'Hide the request and - notify the user:' and customise the text of the email that will be - sent to the user to let them know what you've done. When you're - ready, click the 'Hide request' button. - * <strong>Hiding a request or making it only visible to the - requester without notifying the requester</strong> - In the 'Request metadata' section of the request - admin page, click 'Edit metadata'. Change the 'Prominence' value to - 'requester_only' to only allow the requester to view the request, or - to 'hidden' to hide the request from everyone except site admins. - When you're ready, click 'Save changes' at the bottom of the 'Edit - metadata' section. No email will be sent to the requester to notify - them of what you've done. +You can delete a request from the site. For instructions, see +[deleting a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request). + +Responses to a deleted request will be sent to the holding pen. ### Hiding an incoming or outgoing message @@ -454,4 +835,3 @@ text you wish to replace it with e.g. '[personal information has been hidden]', and a comment letting other admins know why you have hidden the information. - diff --git a/docs/running/categories_and_tags.md b/docs/running/categories_and_tags.md new file mode 100644 index 000000000..f34c8fec3 --- /dev/null +++ b/docs/running/categories_and_tags.md @@ -0,0 +1,196 @@ +--- +layout: page +title: Categories & tags +--- + +# Categories and tags for authorities + +<p class="lead"> + + Use tags to arrange + <a href="{{ site.baseurl }}docs/glossary/#authority" + class="glossary__link">authorities</a> into categories, or to associate + related authorities with each other. This helps your users find the right + authority for the + <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + (or <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">response</a>) + they are interested in. +</p> + +## Categories & category headings + +Alaveteli lets you organise your authorities into *categories*. Categories can +themselves belong to *category headings*. For example, some of the categories +and headings on +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s +<a href="https://www.whatdotheyknow.com/body/list/all">View authorities</a> page look like this: + +> * **Media and culture** +> * Media +> * Museums and galleries +> * **Military and security services** +> * Armed Forces +> * Military colleges +> * Security services +> * **Emergency services** +> * Police forces +> * Fire & rescue services + + +In this example, "Emergency services" is a heading which contains the categories +"Police forces" and "Fire & rescue services". + +Tags are simply searchable words that you can add to an authority. Nominate a +tag for each category: any authority which has that tag is automatically +assigned to the category. For example, if the tag `police` is associated with +the category "Police forces", any authority which has the tag `police` will +appear in that category. + +Make sure you choose good category headings and names, because they help your +users find the specific authorities they are looking for. + +<div class="attention-box info"> + Try to use simple but descriptive words for tags. Tags cannot contain spaces + (use an underscore if you need to, <code>like_this</code>). + Remember that tags will be seen and used by the public (for example, in the + <a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). +</div> + +### Adding a new category + +In the admin interface, click on **Categories**. It's a good idea to create +category headings first (but don't worry if you don't — you can change +them later). + +Click on **New category heading**, enter a name (for example, "Emergency +services") and click **Create**. + +To create a category, click on **New category**. As well as providing a title +and a description, you must enter a category tag. Any authority with this tag +will be assigned to this category. + +Select the checkbox next to the category heading under which you want this +category to be listed. It's common for a category to be under just one heading. +But sometimes it makes sense for a category to go under more than one, so you +can select multiple checkboxes if you need to. + +Click **Save** to create the category. + +### Editing or deleting a category + +Click on **Categories** then find the category in the list (if the category is +under a heading, you may need to click on the heading's chevron to expand the +list to show it). Click the name of the category to select it. You can edit it +and click **Save**. + +If you want to destroy a category, go to edit it but instead of saving it, +click on the **Destroy** button at the bottom of the page. This does not +delete any authorities in that category — they simply no longer belong to +it. + +## Special tags + +Some tags are special. Alaveteli behaves differently when an authority has one +of these tags. + +<table class="table"> + <tr> + <th> + Tag + </th> + <th> + Effect + </th> + </tr> + <tr> + <td> + <code>site_administration</code> + </td> + <td> + This is a test/dummy authority. It is not displayed to the public on your + main site, and it is not included when you + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. + </td> + </tr> + <tr> + <td> + <code>defunct</code> + </td> + <td> + This authority no longer operates: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>not_apply</code> + </td> + <td> + <a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> + law does not apply to this authority: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>eir_only</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + On our UK installation of Alaveteli, + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, + this tag indicates that the authority is subject to an alternative law + (Environment Information Regulations, rather than the Freedom of + Information), which means Alaveteli must change the wording of these + requests appropriately. + </td> + </tr> + <tr> + <td> + <code>school</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> + applies a different definition of "late" if an authority has the <code>school</code> tag. + </td> + </tr> +</table> + +## Custom tags and custom behaviour + +You can add any tag you want — they don't have to be associated with +categories. + +If you are a developer, and you want to add special behaviour to your site +based on your own tags, you need to add custom code, which should probably go +in your own +<a href="{{ site.baseurl}}docs/glossary/#theme" class="glossary__link">theme</a>. +For example, in the UK, schools are granted special concession in the law to allow for +requests that are made out of term-time. Alaveteli handles this by using the +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#special_reply_very_late_after_days) +config value if the authority has the `school` tag. +See +[`is_school?`](https://github.com/mysociety/alaveteli/blob/f0bbeb4abf4bf07e5cfb46668f39bbff72ed7210/app/models/public_body.rb#L391) +and +[`date_very_overdue_after`](https://github.com/mysociety/alaveteli/blob/81b778622ed47e24a2dea59c0529d1f928c68a58/app/models/info_request.rb#L752) +for the source code. + +## Searching with tags + +Alaveteli's +<a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a> +feature (which is available to all your users) can search for specific tags. So +if you add useful tags and publicise them, your users can use them to find +related authorities. For example, see the <a +href="https://www.whatdotheyknow.com/advancedsearch">advanced search on +WhatDoTheyKnow</a> to see this at work. + +You can add reference numbers or specific values to tags using a colon. On +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +we tag all authorities that are charities with the tag `charity:123456` (where +123456 is the authority's registered charity number). + + + + diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md new file mode 100644 index 000000000..5b7f08bec --- /dev/null +++ b/docs/running/holding_pen.md @@ -0,0 +1,101 @@ +--- +layout: page +title: The holding pen +--- + +# The holding pen + +<p class="lead"> + + The <em>holding pen</em> is where Alaveteli puts any incoming + <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a> + that can't be matched to a + <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + automatically. +</p> + + +Alaveteli works by emailing requests to the correct target +<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a>. +That email message is sent from a unique email address — that is, an +email address that is associated with that single request (technically, +Alaveteli hashes the request ID to generate a unique address and uses this as +the `Reply-to:` address). + +So whenever an authority replies (by email) to a request that Alaveteli has +sent, that response will be addressed to that request's unique email address. +The email is received by your installation's +<a href="{{ site.baseurl}}docs/glossary/#mta" class="glossary__link">MTA</a>, +and is passed on to Alaveteli. In this way, incoming messages are easily +matched with the request they are responses to — this is important +because your site displays the responses underneath their original request, on +the request's page. + +Normally, this works fine. But sometimes things go wrong, and a message comes +in that can't be matched with a request. When this happens, Alaveteli puts the +message in the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding +pen </a>. + +Messages wait in the holding pen until an +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +redelivers them to the correct request, or else deletes them. + +## Why messages end up in the holding pen + +There are several reasons why a message might end up in the holding pen: + +* **the authority "broke" the reply-to email**<br> + This can happen if the authority replies "by hand" to the incoming email — + for example if the person at the authority accidentally loses the first + letter of the email address when they copy-and-paste it. Or if they copy + it manually and simply get it wrong. + +* **there's something unusual about the way it was sent**<br> + For example, if it was delivered here because the address is in the `Bcc:` + field, and is not the `To:` address. + +* **a partial email address may have been guessed**<br> + Someone guesses an email address which Alaveteli doesn't recognise. Perhaps + they have misunderstood how the addresses are formed, or maybe it's a + deliberate attempt to send spam. + +* **the response is to a request that has been deleted**<br> + If you [delete a request]({{ site.baseurl }}docs/running/requests/#deleting-a-request), + Alaveteli cannot deliver responses to it. + +* **the response has been rejected and rejections are set to go to the holding pen**<br> + Incoming mail that is correctly addressed but not accepted for the request + goes into the holding pen if the request's `handle_rejected_responses` + behaviour is set to `holding_pen` (rather than bouncing the email back to + the sender, or simply deleting it). Responses may be rejected for various + reasons — for example, if a response is sent from an unrecognised + email address for a request whose *Allow new responses from* setting is + `authority_only`. See instructions on + [how to manage requests]({{site.baseurl}}docs/running/requests/) for details. + +## What to do: redeliver or delete + +You need to be an +<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a> +to modify the holding pen. + +There are two things you can do to a message in the holding pen: + + * **find the right request, and redeliver the message**<br> + Alaveteli tries to guess the right request to help you, so sometimes + you can just accept its suggestion. + + * **delete the message**<br> + If the message is not a response, you can delete it. + +For instructions, see +[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen). + +If the `To:` address does not belong to a valid request and the message is +clearly spam you can add that email address to Alaveteli's +<a href="{{site.baseurl}}#spam-address-list" class="glossary__link">spam address list</a>. +Subsequent messages to that address will be automatically rejected — for +instructions see +[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). + diff --git a/docs/running/requests.md b/docs/running/requests.md new file mode 100644 index 000000000..bf8655949 --- /dev/null +++ b/docs/running/requests.md @@ -0,0 +1,322 @@ +--- +layout: page +title: Managing requests +--- + +# Managing Requests + + +<p class="lead"> + Alaveteli makes it easy for a user to make a + <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a>. + As an + <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">administrator</a>, + there are some things about that request you can change once it’s been created. +</p> + +A request is automatically created when a user submits and (where necessary) +confirms it. Alaveteli sends it to the +<a href="{{ site.baseurl }}docs/glossary/#authority" class="glossary__link">authority</a> +responsible and handles any +<a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">responses</a>. +Usually this process runs without needing any intervention from an +administrator. But sometimes you'll want to change some aspect of the request, +or the way Alaveteli is handling it. + +<ul class="toc"> + <li><a href="#what-state-is-the-request-in">What state is the request in?</a></li> + <li><a href="#changing-things-about-a-request">Changing things about a request</a></li> +<li><a href="#resending-a-request-or-sending-it-to-a-different-authority">Resending a request or sending a request to a different authority</a></li> + <li><a href="#hiding-a-request">Hiding a request</a></li> + <li><a href="#deleting-a-request">Deleting a request</a></li> +</ul> + +## What state is the request in? + +Every request moves through a series of +<a href="{{ site.baseurl }}docs/glossary/#state" class="glossary__link">states</a>, +indicating its progress. Usually a new request will be in the +`waiting_response` state until something happens to change that — for +example, a response is received. + +However, states can't always be set automatically, because they require a +decision to be made on what kind of answer the authority provided in the +response. For states like this, Alaveteli invites the original requester to +describe it — for example, when a response is received they can change +the state to `successful`, `partially_successful` or `not_held` (if the +authority replied to say they don't have the information requested). + +<div class="attention-box info"> + If a request has been waiting for over three weeks for the original + requester to describe it but has still not been described, Alaveteli + lets <em>anyone</em> classify it. +</div> + +Internally, Alaveteli does not just record the "described state" of a request, +but also notices if anything has happened since it was last described and +sets its "awaiting description" status appropriately. + + +## Changing things about a request + +To change any of these settings, go to the +<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +click on **Requests**, then click on the title of the request you want to affect. +Click the **Edit metadata** button. + +<table class="table"> + <tr> + <th> + What you can change + </th> + <th> + Details + </th> + </tr> + <tr> + <td> + Title + </td> + <td> + The <em>title</em> is shown on the request’s page, but is also used + in the URL (the text is changed to lower case, punctuation is removed + and, if necessary, a number is added for disambiguation — this is + called the “slug”). + <p> + Note that changing the title changes the URL, because the slug changes + — this means any links to the <em>old</em> URL will no longer + work, and will return a 404 (file not found) error. + </p> + </td> + </tr> + <tr> + <td> + Who can see it? + </td> + <td> + Change the <strong>Prominence</strong> setting to one of: + <ul> + <li><code>normal</code></li> + <li> + <code>backpage</code>: request can be seen by anyone (by visiting + its URL, for example) but does not appear in lists, or search results + </li> + <li> + <code>requester_only</code>: request only visible to the person who + made the request + </li> + <li> + <code>hidden</code>: request is never shown (except to administrators) + </li> + </ul> + <br> + </td> + </tr> + <tr> + <td> + Who can respond? + </td> + <td> + The <strong>Allow new responses from...</strong> setting can be one of: + <ul> + <li><code>anybody</code></li> + <li> + <code>authority_only</code>: responses are allowed if they come + from the authority to which the request was sent, or from any domain + from which a a response has <em>already</em> been accepted + </li> + <li> + <code>nobody</code>: no responses are allowed on this request + </li> + </ul> + Any response from a sender who has been disallowed by this + setting will be rejected (see next entry). + </td> + </tr> + <tr> + <td> + What happens to rejected responses? + </td> + <td> + The <strong>Handle rejected responses...</strong> setting specificies + what happens to responses that are not allowed (see previous entry): + <ul> + <li> + <code>bounce</code>: responses are sent back to their sender + </li> + <li> + <code>holding pen</code>: responses are put in the + <a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a> + for an administrator to deal with + </li> + <li> + <code>blackhole</code>: responses are destroyed by being sent to a + <a href="{{ site.baseurl }}docs/glossary/#blackhole" class="glossary__link">black hole</a> + </li> + </ul> + </td> + </tr> + <tr> + <td> + What state is it in? + </td> + <td> + See <a href="{{ site.baseurl }}docs/customising/states/">more about + request states</a>, which can be customised for your installation. + <p> + You can force the state of the request by choosing it explicitly. + Change the <strong>Described state</strong> setting. + </p> + <p> + You may also need to set <strong>Awaiting description</strong> if, + having changed the state, you want the original requester to update the + description. For example, if the state depends on the information + within the response, and you want the requester to classify it — + see + <em><a href="#what-state-is-the-request-in">What state is the request in?</a></em> + above. + </p> + </td> + </tr> + <tr> + <td> + Are comments allowed? + </td> + <td> + The <strong>Are comments allowed?</strong> setting simply you choose to + allow or forbid annotations and comments on this request. + <p> + Note that this won’t hide any annotations that have already + been left on the reques — it only prevents users adding new ones. + </p> + </td> + </tr> + <tr> + <td> + Tags (search keywords) + </td> + <td> + Enter tags, separated by spaces, that are associated with this request. + A tag can be either a simple keyword, or a key-value pair (use a colon as + the separator, like this: <code>key:value</code>). + <p> + Tags are used for searching. Users and administators both benefit if + you tag requests with useful keywords, because it helps them find + specific requests — especially if your site gets busy and there + are very many in the database. + </p> + <p> + Although it’s a little more complex than tags on requests, + <a href="{{ site.baseurl }}docs/glossary/#category" class="glossary__link">categories</a> + also use tags: + see + <a href="{{ site.baseurl }}docs/running/categories_and_tags/">more about tags</a> + for a little more information. + </p> + </td> + </tr> +</table> + +## Resending a request or sending it to a different authority + +If you have corrected the email address for an authority, you can resend +an existing request to that authority to the new email address. Alternatively, +a user may send a request to the wrong authority. In that situation, you can +change the authority on the request and then resend it to the correct authority. + +To resend a request, go to +the <a href="{{ site.baseurl }}docs/glossary/#admin" +class="glossary__link">admin interface</a>, click on **Requests**, then +click on the name of the request you want to change. Go to the **Outgoing messages** heading. Click the chevron next to the first outgoing message, which is the initial request. A panel of information about that message will appear. Click on the **Resend** button. + +To send a request to a different authority, go to +the <a href="{{ site.baseurl }}docs/glossary/#admin" +class="glossary__link">admin interface</a>, click on **Requests**, then +click on the name of the request you want to change. In the **Request +metadata** section, there is a line which shows the authority. Click the +**move...** button next to it. Enter the **url_name** of the authority +that you want to send the request to. + +<div class="attention-box info"> +Users, requests and authorities all have <strong>url_names</strong>. This can be found in the metadata section of their admin page. The <code>url_name</code> makes up the last part of the URL for their public page. So, for a request with the <code>url_name</code> “example_request”, the public page URL will be <code>/request/example_request</code>. +</div> + +Now click the **Move request to +authority** button. You will see a notice at the top of the page telling +you that the request has been moved. You can now resend the request as above. + + +## Hiding a request + +You can hide an entire request. Typically you do this if it's not a valid +Freedom of Information request (for example, a request for personal +information), or if it is vexatious. + +Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +click on **Requests**, then click on the title of the request you want. You can +hide it in one of two ways: + + * [Hide the request and notify the requester](#hide-the-request-and-notify-the-requester) + * [Hide the request without notifying the requester](#hide-the-request-without-notifying-the-requester) + +Responses to a hidden request will be accepted in the normal way, but because +they are added to the request's page, they too will be hidden. + +### Hide the request and notify the requester + +Scroll down to the *Actions* section of the request's admin page. +Choose one of the options next to **Hide the request and notify the user:** + + * Not a valid FOI request + * A vexatious request + +Choosing one of these will reveal an email form. Customise the text of the +email that will be sent to the user, letting them know what you've done. When +you're ready, click the **Hide request** button. + +### Hide the request without notifying the requester + +<div class="attention-box helpful-hint"> + As well as hiding the request from everyone, you can also use this method if + you want to make the request only visible to the requester. +</div> + +In the *Request metadata* section of the request's admin page, click the +**Edit metadata** button. Change the *Prominence* value to one of these: + + * `requester_only`: only the requester can view the request + * `hidden`: nobody can see the request, except administrators. + +<div class="attention-box warning"> + If you want to hide the request, do not chooose <code>backpage</code> + as the prominence. The <code>backpage</code> option stops the request + appearing in lists and searches so that it is effectively only visible + to anyone who has its URL — but it <em>does not hide</em> the request. +</div> + +When you're ready, click the **Save changes** button at the bottom of the +*Edit metadata* section. No email will be sent to the requester to notify +them of what you've done. + + +## Deleting a request + +You can delete a request entirely. Typically, you only need to do this if +someone has posted private information. If you delete a request, any responses that it has already received will be +destroyed as well. + +<div class="attention-box warning"> + Deleting a request destroys it. There is no “undo” operation. + If you're not sure you want to do this, perhaps you should + <a href="#hiding-a-request">hide the request</a> instead. +</div> + +Go to the <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, +click on **Requests**, then click on the title of the request you want to delete. +Click the **Edit metadata** button. Click on the red **Destroy request entirely** +button at the bottom of the page. + +Responses to a deleted request will be sent to the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>. + + diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 533035892..81af8289f 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -6,10 +6,10 @@ Upgrading Alaveteli ==================== <p class="lead"> - Alaveteli is under active development — don't let the - version you're running get too far behind our latest + Alaveteli is under active development — don’t let the + version you’re running get too far behind our latest <a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release</a>. - This page describes how to keep your site up-to-date + This page describes how to keep your site up to date. </p> ## How to upgrade the code @@ -29,23 +29,26 @@ 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. -## Alaveteli Version Numbers +<div class="attention-box info"> + You don't need to run the script if you're using Capistrano, because the + deployment mechanism automatically runs it for you. +</div> -Alaveteli uses a shifted version of [semver](http://semver.org). +## Alaveteli version numbers -- Series `W` -- Major `X` -- Minor `Y` -- Patch `Z` +Alaveteli uses a “shifted” version of [semver](http://semver.org) +(just as [Rails version numbering](http://guides.rubyonrails.org/maintenance_policy.html) +does). This means that version numbers are of the form: `SERIES.MAJOR.MINOR.PATCH`. -At the time of writing the current release is `0.19.0.6`: +At the time of writing, the current release is `0.19.0.6`: - Series `0` - Major `19` - Minor `0` - Patch `6` -Alaveteli will transition to the [semver](http://semver.org) specification when it reaches `1.0.0`. +We'll use the [semver](http://semver.org) specification for Alaveteli's +version numbering when it reaches `1.0.0`. ## Master branch contains the latest stable release @@ -73,7 +76,7 @@ Patch version increases (e.g. 0.1.2.3 → 0.1.2.**4**) should not require any Minor version increases (e.g. 0.1.2.4 → 0.1.**3**.0) will usually require further action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) document to see what's changed since your last deployment, paying special attention to anything in the "Upgrade notes" sections. Any upgrade may include new translations strings, that is, new or altered messages -to the user that need translating to your locale. You should visit Transifex +to the user that need translating to your locale. You should visit <a href="{{ site.baseurl }}docs/glossary/#transifex" class="glossary__link">Transifex</a> 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 @@ -92,7 +95,7 @@ Only major releases may remove existing functionality. You will be warned about Special instructions will accompany series releases. -## Deprecation Notices +## Deprecation notices You may start to see deprecation notices in your application log. They will look like: |