diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/installing/macos.md | 14 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 58 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 27 |
3 files changed, 63 insertions, 36 deletions
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/running/admin_manual.md b/docs/running/admin_manual.md index e82758390..cb1443578 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -34,6 +34,8 @@ In this guide: <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="#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="#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> @@ -312,7 +314,7 @@ line, and piping the contents of that file into the mail handling script. e.g. 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. +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). @@ -343,7 +345,7 @@ have extra privileges in the main website front end. Administrators can: Alaveteli puts incoming messages (that is, <a href="{{ site.baseurl }}docs/glossary/#reponse" class="glossary__link">responses</a>) -into the +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>. @@ -375,7 +377,7 @@ your attention. Click on any one of them to see the details. 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 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. @@ -397,7 +399,7 @@ its *url_title*. <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 + In the URL <code>/request/how_many_vehicles</code>, the <em>url_title</em> is <code>how_many_vehicles</code>. </p> </div> @@ -413,7 +415,7 @@ in the holding pen, and is shown instead on the public request page. ### Rejecting spam that arrives in the holding pen -Alaveteli maintains a +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 @@ -461,13 +463,13 @@ 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 +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 +running in your <a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. ### Creating, changing and uploading public authority data @@ -580,7 +582,7 @@ unrecognised column name, the import will fail. 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 + 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. @@ -595,7 +597,7 @@ unrecognised column name, the import will fail. 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 + * 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"`). @@ -612,15 +614,15 @@ data (one line for each authority): 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. +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. @@ -638,7 +640,7 @@ you really uploaded this data, followed by a message like this: 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 +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. @@ -684,6 +686,34 @@ Find the user you wish to ban on the list and click on their name. Once on the u 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. +### Allowing a user to make more requests + +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. + +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. + +### Batch requests + +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. + +<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> + +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. + ### Hiding a request If a request contains vexatious or inappropriate content, is libellous, or is @@ -699,7 +729,7 @@ they are added to the request's page, they too will be hidden. ### Deleting a request -You can delete a request from the site. For instructions, see +You can delete a request from the site. For instructions, see [deleting a request]({{ site.baseurl }}docs/running/requests/#deleteing-a-request). Responses to a deleted request will be sent to the holding pen. diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index 533035892..32146a3c6 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 @@ -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: |