How to Package a New RMG Release

Release Numbering

RMG-Py and RMG-database releases can be different versions, and a new database release does not have to coincide with an RMG-Py release. Release numbering should be updated based on how much the code has shifted. We currently use a naming system like so

RMG-Py vX.Y.Z  

Git Workflow

We have incorporated some elements of Git Flow into our workflow. There are now separate stable and master branches. Releases are tagged on the stable branch, which is only updated for releases. The master branch is essentially the develop branch and contains all ongoing work. Releases should start as a new branch created off of master, upon which release related changes are made, such as updating the version number and documentation. The release branch should then be merged into the stable branch, creating the release, and also the master branch, to make sure all changes are incorporated.

Release Creation

1. When RMG-Py and/or RMG-database are ready for a new release, first create release branches off of master, i.e. vX.Y.Z. Development can continue on the master branches after the release branch has been created.

2. Update all version numbers first, because a lot of the other files and functions queries these version numbers.

   • For RMG-Py: RMG-Py/rmgpy/version.py, RMG-database version requirement in RMG-Py/meta.yaml if necessary
   • For RMG-database: RMG-database/setup.py
   • For PyDQED: PyDQED/setup.py, PyDQED/pydqed.pyx
   • For PyDAS: PyDAS/pydas/version.py

3. Create new release notes in the documentation for the version: RMG-Py/documentation/source/users/rmg/releaseNotes.rst

4. Make sure main copyright stamps to reflect year change if necessary in RMG-Py/LICENSE.txt

5. Compile new PDF documentation from source for the release by going into documentation folder and using the command make latexpdf. Replace the previous documentation pdfs in the RMG-Py/documentation folder. Create a commit that states that PDF documentation for release X.Y.Z has been updated. (Note that RMG-Py, PyDAS, and PyDQED repos all have documentation. RMG-database does not.)

6. Update the online documentation too (see the wiki page for details: https://github.com/ReactionMechanismGenerator/RMG-Py/wiki/Updating-Documentation).

7. Check that everything works correctly. Unit tests are automatically run by Travis. RMG-tests is also automatically triggered. Confirm that both pass without issues by pushing the release branch to GitHub. You may want to test that the Anaconda binary for the repo compiles correctly at this point in time and that the packages run properly on a clean anaconda environment.

   • Example testing procedure in Mac and Linux:

     conda create --name rmg_test -c rmg rmg=X.Y.Z
     source activate rmg_test
     rmg.py input.py
     source deactivate
     

8. Once you're sure that the release is ready, then it can be merged into the stable branch. This can either be done locally or via a GitHub pull request. If doing locally, switch to the stable branch and run git merge --no-ff vX.Y.Z -m "RMG-Py vX.Y.Z release". Modify the commit message appropriately for other repos. If doing via GitHub, be sure to modify the merge commit message.

9. Go to the releases tab of the repository and click the 'Draft a new release' button. Tag the version with the string X.Y.Z and create the release title RMG-Py vX.Y.Z. You can also create a tag locally using git tag X.Y.Z, then push to GitHub and draft the release.

10. Once the changes have been pushed to the stable branches on GitHub, Travis will automatically compile and upload the binaries for Linux-64 and OSX-64. Important Note: If updating the version requirement of RMG-database in RMG-Py, the new binary for RMG-database must be uploaded before the RMG-Py binary is created. Generally, this just means that you should push to RMG-database stable before RMG-Py stable in order to give Travis time to finish.

11. Some binary version of RMG dependencies which have expiration date need also be updated. So far we have mopac to be updated.

12. Now update any relevant version numbers in the repo https://github.com/ReactionMechanismGenerator/ReactionMechanismGenerator.github.io, which generates the homepage http://reactionmechanismgenerator.github.io

13. Update the version number on the Green Group website: http://greengroup.mit.edu/reaction-mechanism-generator/

14. If the release had substantial updates, email this news to the relevant RMG userbase along with the release notes and links for how to install. Reference older release emails for details. (Key groups: sourceforge mailing list, rmg_dev@mit.edu, Green Group, Comocheng Group, any users who have been emailing us in recent history).