Skip to content

How to Package a New RMG Release

Jump to bottom
Max Liu edited this page Jun 17, 2019 · 26 revisions

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. However, because RMG-Py and RMG-database development is often closely linked, it is a good idea to make releases for both on the same schedule.

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

very loosely following the concept of semantic versioning, e.g. Z updates should contain bugfixes, Y updates should contain feature level changes, and X updates should contain backward-incompatible changes.

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. The stable branch should then be merged back into master to ensure that changes associated with the release are incorporated, and that the version tag is also visible on master.

The primary benefit of this workflow is that hotfixes to released versions are possible. For example, if development has already progressed on the master branch when a major bug is discovered, we can fix the bug and push a patch release without being forced to include the latest developments into the release. To do so, the hotfix branch should be created from stable, the fixes applied, and then merged back into stable to create the release. The stable branch can then be merged into master again to ensure that the changes are on master.

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/.conda/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. If an updated is needed, make the change in the LICENSE.txt file and then run RMG-Py/utilities.py update-headers. Make sure to review the changes in case there are any files which were processed incorrectly.

  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. 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

  7. 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.

  8. 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.

  9. 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.
    • Automatic uploading of the binaries to Anaconda.org is enabled by an authentication token saved to the CONDA_TOKEN environment variable via Travis CI. The current token will expire on 6/14/21, at which point an new token will need to be generated (either via Anaconda.org or from the command line).

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

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

Items which are now automatically updated (but should be double checked):

Home

RMG

Anaconda

Github/Travis

Clone this wiki locally