Merge branch 'gh-pages' of ssh://git.mysociety.org/data/git/public/alaveteli into gh-pages

2 files changed, 64 insertions, 9 deletions

diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index 77bacdf1b..cde828c9a 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -297,5 +297,24 @@ hanging the application altogether), so please:
 * Restrict your use of them to cases that can't otherwise be easily covered.
 * Keep them as simple and specific as possible.
 
+## Administrator privileges
 
+The administrative interface is at the URL `/admin`.
 
+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.
+
+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`.
+
+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.
+
+It is possible completely to override the administrator authentication by
+setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`.
diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md
index a3b292cf0..2142bfd47 100644
--- a/docs/running/upgrading.md
+++ b/docs/running/upgrading.md
@@ -5,20 +5,53 @@ title: Upgrading
 Upgrading Alaveteli
 ====================
 
-The developer team policy is that the master branch in git should always
-contain the latest stable release. Therefore, in production, you should usually
-have your software deployed from the master branch, and an upgrade can be
-simply `git pull`.
+<p class="lead">
+  Alaveteli is under active development &mdash; 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
+</p>
+
+## Master branch contains the latest stable release
+
+The developer team policy is that the `master` branch in git should always
+contain the latest stable release -- so you'll be up to date if you pull from
+the `master` branch. However, on your
+<a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production
+site</a>, you should know precisely what version you're running, and deploy
+Alaveteli from a [*specific* release
+tag](https://github.com/mysociety/alaveteli/releases).
+
+Upgrading may just require pulling in the latest code -- but it may also require
+other changes ("further action"). For this reason, for anything other than a
+*patch* (see below), always read the 
+[`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md)
+document **before** doing an uprade. This way you'll be able to prepare for any
+other changes that might be needed to make the new code work.
+
+## How to upgrade the code
+
+* If you're using Capistrano for deployment,
+  simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage):
+  set the repo and branch in `deploy.yml` to be the version you want. 
+  We recommend you set this to the explicit tag name (for example, 
+  `0.18`, and not `master`) so there's no risk of you accidentally deploying
+  a new version before you're aware it's been released.
+* otherwise, you can simply upgrade by running `git pull`
+
+## Patches
 
 Patch version increases (e.g. 1.2.3 &rarr; 1.2.**4**) should not require any further
 action on your part.
 
+## Minor version increases
+
 Minor version increases (e.g. 1.2.4 &rarr; 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.
+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, i.e. new or altered messages
+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
 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
@@ -26,7 +59,10 @@ your website in English by default. If your translations didn't make it to the
 latest release, you will need to download the updated `app.po` for your locale
 from Transifex and save it in the `locale/` folder.
 
-Unless you're using Capistrano for deployment, you should always run the script `scripts/rails-post-deploy` after each
+## Run the post-deploy script
+
+Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/),
+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.