HowToRelease

Some developer notes on how to do a release. These instuctions are intended for a new major or minor version. For a micro version some instructions must be ignored or adapted. Replace vX.Y.Z with the appropriate version number.

Pre-release

1. Search for all TODOs, FIXMEs, and XXXs in the code to make sure that nothing important slips in.

2. Do a run of pydocchecker to fix the type annotations.

3. Send a call for translations when strings are stable, like http://www.freelists.org/post/contestms/Call-for-translations

Release.

FIXME: Change the documentation to link to the attached .tar.gz archive instead of the autogenerated one.

1. Checkout the master branch:

   git checkout master
   

2. Update the version number in the source files (there's one occurrence in cms/__init__.py and one in docs/conf.py) and commit these changes with a message like:

   Version X.Y.Z
   
   https://github.com/cms-dev/cms/wiki/CMS-X.Y.Z-RELEASE-NOTES
   

   Example.

3. Create a new page in the wiki containing the release notes, and update the history page to link to that page.

4. Create a branch for the new version (without the micro):

   git branch vX.Y
   

5. Push both the master and the vX.Y branches:

   git push origin master vX.Y
   

6. Open https://github.com/cms-dev/cms/releases, click on "Draft a new release", insert vX.Y.Z as tag name and select the vX.Y branch as target. Write some release notes (with some sensible content!). Manually create a .tar.gz archive with the sources and attach it (this is needed because the archive autogenerated by GitHub will not include isolate since it's a git submodule, thus be sure to make the archive with a clean and complete checkout). That is:

   git clone https://github.com/cms-dev/cms.git
   cd cms
   git submodule update --init
   rm -rf .git isolate/.git
   cd ..
   tar zcf vX.Y.Z.tar.gz cms

   Publish the release.

7. Wait for the new branch (the branch, not the tag!) to pop up in the ReadTheDocs control panel (it takes a bit for RTD to realize that a new branch has been pushed; I did not find any way to force it). Then activate it in the Version page and make it default in the Admin page.

8. Check that all the relevant automatic links have been created by GitHub, so that there are no 404 errors around (in the wiki and in the docs). Also check that the documentation has been compiled correctly.

9. Push the new version numbers for the stable and the development versions on the website (for the stable version, update also the URLs of the links).

10. Send the release notes to the mailing list (for reference: http://www.freelists.org/post/contestms/CMS-100-RELEASE-NOTES).

11. Set the version numbers in the source files to the next version (there's one occurrence in cms/__init__.py and two in docs/conf.py, and remember to append a dev!)

12. Close the milestone on GitHub.

13. It is now a good time to do all those things that should be done at the beginning of the release: upgrade the python dependencies (e.g., to the versions in the most recent Ubuntu LTS), merge large PRs, ...