Alaveteli

EN

Upgrading Alaveteli

Alaveteli is under active development — don’t let the version you’re running get too far behind our latest release. This page describes how to keep your site up to date.

  • 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. The code will be updated and any post-deploy procedures will automatically run.

Manual upgrade

If you are not able to use Capistrano to update your site, you will need to perform a manual upgrade.

Update the code

  • Navigate to your site directory (likely to be /var/www/YOUR-SITE/alaveteli/)
  • Run git pull as the alaveteli user to avoid access permission errors for site files with the command sudo -u alaveteli git pull

Run the post-deploy script

  • Still in your site directory (/var/www/YOUR-SITE/alaveteli/), run the post-deploy script as the alaveteli user by issuing sudo -u alaveteli script/rails-post-deploy

Do this after each manual deployment as 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 (just as Rails version numbering 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:

  • Series 0
  • Major 19
  • Minor 0
  • Patch 6

We’ll use the semver specification for Alaveteli’s version numbering 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 contain the latest stable release – so you’ll be up to date if you pull from the master branch. However, on your production site, you should know precisely what version you’re running, and deploy Alaveteli from a specific release tag.

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 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.

Patches

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. 0.1.2.4 → 0.1.3.0) will usually require further action. You should read the 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 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 latest release, you will need to download the updated app.po for your locale from Transifex and save it in the locale/ folder.

Minor releases will be backwards compatible with the current major release version.

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 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 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.

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.