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

4. Test manually all those parts that are not tested automatically and don't appear often in the development workflow, including the following.

   • RPC from AWS (e.g., submission queue).
   • RS and resource page (graphs, ability to kill and autorestart service, and set not to autorestart).
   • Notification (web & desktop) in AWS and CWS for questions, announcements, ...
   • Datasets operations (make live, score comparison, automessaging).
   • Auto update of scores in CWS.
   • CWS localization.
   • Everything about RWS.
   • Running AWS/CWS/RWS on non-base URLs.
   • User tests.
   • Tokens.
   • Analysis mode, unofficial submissions.
   • IP autologin.

Release.

1. Checkout the master branch (or the vX.Y branch if this is not the first release for vX.Y):

   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, copying the structure from a previous release (changing the date and the link to what will be the package URL), 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 (if this is the first release for vX.Y) 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 version and select the vX.Y branch as target. Leave the release title blank, and copy the release notes (apart from the first two lines with date and link). 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 checkout vX.Y
   git submodule update --init
   rm -rf .git .gitmodules 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, that is vX.Y) 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). Go to Admin, Version; activate the version vX.Y and declare it the stable version.

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 cms-dev.github.io (for the stable version, update also the URLs of the links).

10. Send the release notes to the mailing list copying the text version from the wiki (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, ...