Release Manager's checklist

This is a checklist of things to do in order to make a new release of alaveteli, which involves creating a release branch according to the git flow model, updating translations, and letting various people know. For more details on translation, see the translation documentation. For more details on git flow, see this description.

The process begins when the develop branch (almost) reflects the desired state of the new release.

Before the release candidate date

• Decide what features should be in the release - are there any must-have bug fixes there are in progress (or could be worked on) that the release should wait for, are there any things that are out of scope that shouldn't be merged until after the release?
• Pick a date for the release branch to be cut ("release candidate date")
• Make an announcement to the translators that they should ensure they have any pending translations saved in Transifex before the release candidate date (ideally this should made on a Wednesday or Thursday with the date set to early the following week to give volunteer translators a mix of work hours and a full weekend to get their work finished off). Be prepared for possible replies asking for a short delay!
• Make sure any recent migrations have corresponding model annotations (bundle exec rails annotate_models). There shouldn't be any changes as this is now run automatically when migration the database. Make sure you don't have any feature branch migrations applied to your development database while running this.
• Remove any deprecated code scheduled for removal in this release - you can find it by grepping for [DEPRECATION] in the code
• Test supported operating systems to make sure there haven't been dependency/install regressions
• Add a description of the release to the Changes file in the release branch - this should include:
  • A list of all major features

git log --oneline --topo-order --show-linear-break master...develop

• Are there any migrations?

git diff --name-only master..develop db/migrate

• Is commonlib updated?
• Are templates changed? (needs a note for people who customise them in their theme)

git --no-pager diff --name-only --diff-filter=DMRT master..develop app/views

• Anything else re-users need to know?

On the release candidate date

• Remove any temp tasks that are no longer needed.
• Commit translations to a hotfix for the current release version, so they are preserved against the last known good msgids. This needs to be done before pushing new strings for translation.
• Download the current translations (Install transifex-client)

tx pull -a -f
# For some reason tx doesn't pull the en locale with -a
tx pull -l en -f

• Convert the translations to a standard msgmerge format

bundle exec rake gettext:clean
bundle exec rake gettext:clean_alaveteli_pro

• Check the translations for XSS insertion
• Check as far as possible for mistakes which may break translations (missing variables, wrong variable names, broken HTML tags)
• Commit the translations (This is important! There's no revision history in Transifex!)

git add locale/
git add locale_alaveteli_pro/
git commit -m 'Update translations'

• Regenerate the POT file and individual PO files for each language. (If the latter only creates the file locale/im-config.pot then you need to unset the TEXTDOMAIN environment variable and try again.)

bundle exec rake gettext:store_model_attributes
bundle exec rake gettext:find
bundle exec rake gettext:find_alaveteli_pro

• Check source language files (locale/en/app.po & locale_alaveteli_pro/en/app.po) for fuzzy strings and correct msgstr otherwise Transifex might not accept the new strings. This can happen when translates have been changed slightly.

• Reupload the POT and PO files to Transifex from the current development branch

tx push -s -t --skip
tx push -s -t --skip -l en

NOTE: Transifex don't support en_RW, so you get what looks like an error when pushing the translations:

Pushing translations for resource alaveteli.apppot:
Pushing source file (locale/en/app.po)
Pushing 'aln' translations (file: locale/aln/app.po)
Pushing 'en_RW' translations (file: locale/en_RW/app.po)
Exception: Not Found

• Re-pull from Transifex to remove the fuzzy strings from the local PO files

tx pull -a -f
tx pull -l en -f

• Manually clean files not supported by Transifex (en_RW, en_UG)

msgattrib --no-fuzzy -o locale/LANG/app.po locale/LANG/app.po

• Clean the pulled files and run the specs.

bundle exec rake gettext:clean
bundle exec rake gettext:clean_alaveteli_pro
bundle exec rspec

You may need to manually remove obsolete msgids.

find locale/* -name *.po | xargs -I % msgattrib --no-obsolete -o % %
bundle exec rake gettext:remove_fuzzy
bundle exec rake gettext:remove_fuzzy_alaveteli_pro
bundle exec rake gettext:clean
bundle exec rake gettext:clean_alaveteli_pro

Assuming the specs pass, commit.

git add locale/
git add locale_alaveteli_pro/
git commit -m 'Generate translations'

• Run brakeman

# Make sure brakeman is up to date
gem update brakeman
# Generate a report
brakeman
open tmp/brakeman.html

# Compare new/fixed against last release
git checkout master
brakeman
git checkout develop
brakeman -o tmp/brakeman-compare.json --compare tmp/brakeman.json
open tmp/brakeman-compare.json

• Look for deprecation notices; remove code
• Test/fix the release
  • Test the happy paths of new features
  • Check that bugfixes actually fix the bugs
• Create the release branch from the develop branch - call it release/[release number]

git checkout -b release/[release number] develop
git push origin release/[release number]

• Send a message to the dev group to let people know they can try the release branch
• Make sure that all dependent themes (alavetelitheme, whatdotheyknow-theme) have develop branches that are compatible with the release branch
• Send a message to the designers to review how design changes have integrated
• Fix any issues reported by testers & designers

On the release date

• Download and commit all the current translations to the current release branch

tx pull -a -f
# You may need to manually remove obsolete msgids
# https://gist.github.com/crowbot/2a2e576d791ceac5f24f564f1d32db89.
find locale/* -name *.po | xargs -I % msgattrib --no-obsolete -o % %
find locale_alaveteli_pro/* -name *.po | xargs -I % msgattrib --no-obsolete -o % %
bundle exec rake gettext:clean
bundle exec rake gettext:clean_alaveteli_pro
bundle exec rspec && git commit -m "Update translations" locale/ locale_alaveteli_pro/

• Check doc/CHANGES.md is up to date with any fixes made on the release branch.
• Update the current version in doc/CHANGES.md
• Update the ALAVETELI_VERSION constant in the release branch (config/initializers/alaveteli.rb).
• Merge the release branch into master

git checkout master
git merge --no-ff release/[release number]

• Tag that commit on the master branch with the release number

git tag -a [release number] -m "[release number]"

• Push the release and the tag

git push origin master
git push origin refs/tags/[release number]

• Merge the release back into the develop branches

git checkout develop
git merge --no-ff master
git push origin develop

• Make sure that all dependent themes (alavetelitheme, whatdotheyknow-theme) have master branches that are compatible with the release branch
• Tag all the dependent themes with a use-with-alaveteli-x.x.x tag
• Send a message to the dev group with a link to the Changes file
• Delete any topic branches that have been now merged to master (find candidates with git branch --merged master)
• Add the release details to the GitHub releases page
• Tweet and/or blog about the new release!