You decided it’s time for a new release… Good!

Before doing anything, ensure all the changes are mades and committed.

Think twice at each step.

Hint If it’s a first experience for you, try doing the process against your own public fork. ,-)

Request for advices If you’re in doubt, request help to a more experienced maintainer. We are here to help and blaming is not our way of working with each other. We ALL did crap at some point in time.

The releases conventions

There are 3 kind of releases we do:

  • stable: vX.Y.Z
    • X: Major release number, currently 6 which didn’t change since May, 2008 (it’s good like that).
    • Y: Big release number, used for big code changes, API changing, backard compatibily issues.
    • Z: Minor release number, any other changes.
  • release candidate: vX.Y.Z-rcN
    • Before releasing a stable version, we publish candidates to avoid intoducing too many bugs.
    • Make as many candidates as you think it worth.
  • maintenance: vX.Y.Z.K
    • Should be avoided; it’s only usefull for backporting big bug fixes and strong security issues.
    • Should be based on the previous stable branch (current stable Y - 1).
    • They are released only in the maint branch.

The release.sh will do all the boring job for you. Il will prompt you to edit the version in the code, write the Changelog from the git history, prepare the announce, etc.

$ ./contrib/release.sh

Once done, publish everything.

Doing the job manually

Prepare the Changelog

First, edit Changelog.md to reflect the release. Add a new entry on top of the previous release and don’t change anything else.

Hint: The Git history is a good start. Use git shortlog $(./offlineimap.py --version).. or git log $(./offlineimap.py --version)...

Update the version

Edit offlineimap/__init__.py and update the version.

Commit and release

$ git commit -a -s -m<vX.Y.Z[-rcN]>
$ git tag -a -s -m<vX.Y.Z[-rcN]> <vX.Y.Z[-rcN]>

Check the changes:

$ git log -p

Merge into the mainline

$ git checkout master
$ git merge next

Update the APIs on the website

Use the Makefile! Amongs the APIs, other files might be updated as the Changelogs, for example.

Pre-requisite You must have sphinx installed and the sphinx-build in your $PATH.

$ cd docs
$ make websitedoc
$ cd ../website
$ git checkout -b next master
$ git add \_doc/versions
$ git commit -a -s -m'import offlineimap API <vX.Y.Z[-rcN]>'
$ git checkout master
$ git merge next

Push the changes

Make your checks! Before publishing anything, ensure things are correct:

  • the Changelog.md is fine
  • the tag of the release is set correctly
  • the next history looks good
  • the master branch is updated
$ git push OfflineIMAP master:master
$ git push OfflineIMAP next:next
$ git push OfflineIMAP <tag>:<tag>

Finally, push the changes of the updated website.

$ cd website
$ git push website master:master

DO NOT use fancy shortened command Shortened commands like git push, git push --all or git push --tags tend to push way too much things by default. Keep control of what make public!

Hint: If despite the BIG warning you’ve push too much, delete the offender branches/tags with git push OfflineIMAP :<offender>

Send the announce

Finally, send the announce to the mailing list. If you used the release.sh script, one was prepared for you in .git/offlineimap-release/announce.txt.

You’re done!

Update the issue tracker

While not urgent, it’s good to keep the issue tracker up-to-date. Defer this task if you wish.

Also, update the milestones.