diff options
Diffstat (limited to 'docs/running/upgrading.md')
| -rw-r--r-- | docs/running/upgrading.md | 87 |
1 files changed, 65 insertions, 22 deletions
diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index ab8db2385..533035892 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -12,6 +12,41 @@ Upgrading Alaveteli This page describes how to keep your site up-to-date </p> +## 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` + +## 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. + +## Alaveteli Version Numbers + +Alaveteli uses a shifted version of [semver](http://semver.org). + +- Series `W` +- Major `X` +- Minor `Y` +- Patch `Z` + +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`. + ## Master branch contains the latest stable release The developer team policy is that the `master` branch in git should always @@ -26,30 +61,16 @@ 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 +document **before** doing an upgrade. 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 → 1.2.**4**) should not require any further -action on your part. +Patch version increases (e.g. 0.1.2.3 → 0.1.2.**4**) should not require any further action on your part. They will be backwards compatible with the current minor release version. ## Minor version increases -Minor version increases (e.g. 1.2.4 → 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. +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 @@ -59,10 +80,32 @@ 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. -## Run the post-deploy script +Minor releases will be backwards compatible with the current major release version. -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. +## Major releases + +Major version increases (e.g. 0.1.2.4 → 0.2.0.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. + +Only major releases may remove existing functionality. You will be warned about the removal of functionality with a deprecation notice in a minor release prior to the major release that removes the functionality. + +## Series releases + +Special instructions will accompany series releases. + +## Deprecation Notices + +You may start to see deprecation notices in your application log. They will look like: + + DEPRECATION WARNING: Object#id will be deprecated; use Object#object_id + +Deprecation notices allow us to communicate with you that some functionality will change or be removed in a later release of Alaveteli. + +### What to do if you see a deprecation notice + +You will usually see a deprecation notice if you have been using functionality in your theme that is now due to change or be removed. The notice should give you a fair explanation of what to do about it. Usually it will be changing or removing methods. The [changelog](https://github.com/mysociety/alaveteli/blob/rails-3-develop/doc/CHANGES.md) will include more detailed information about the deprecation and how to make the necessary changes. + +If you're ever unsure, don't hesitate to ask in the [developer mailing list](https://groups.google.com/group/alaveteli-dev) or [Alaveteli IRC channel](http://www.irc.mysociety.org/). + +### When will the change take place? +We introduce deprecation notices in a **minor** release. The following **major** release will make the change unless otherwise stated in the deprecation notice. |