Cutting a release

WaterTAP: Cutting a Release

We endeavor to follow PEP 440 for how we version our releases.

Creating a new Proteuslib release is broken down into a few (possibly repeating) steps:

1. First on github, create a new "release" branch, named after just the major and minor versions for the release. For example if preparing for a 1.1.0 release, create a branch named 1.1_rel. Release candidate tags (i.e. 1.1.0rc0), final release tags (i.e. 1.1.0) and patch release tags (i.e. 1.1.1) will all exist on this branch.

2. Clone/checkout that new branch and update the version number in ./docs/conf.py and ./setup.py on this release branch (to version used above)

3. Update install_requires in setup.py, change:

   *SPECIAL_DEPENDENCIES_FOR_PRERELEASE
   

   to

   *SPECIAL_DEPENDENCIES_FOR_RELEASE
   

4. Commit and push those changes to the release branch up to github.

5. Create the new release in github on the release branch using the github releases page to create a new tag and release on the new release branch (not main). Fill in the new tag to create, the name of the release, the release notes, select the "pre-release" checkbox for release candidates then publish.

6. Back in your clone of the release branch, git pull to bring down the new release tag. A git describe --tags --dirty should show the correct release tag now.

7. Now on main, if not already done, change the same ./docs/conf.py and ./setup.py to have the dev version of the next release, i.e 1.2.0dev and push that up to main, since that is now the dev version of the next release.

8. For final (non-release candidate) releases I will also delete any outdated release candidates on github - which will NOT remove the tags created but will remove the headings for the old releases. I do this just to make that page a little cleaner and to avoid confusion with older releases.

9. Update readthedocs so that it builds the tags (the new release) that you want it to. For final releases make sure that RTD's stable tag now points to the new final release. The latest tag always should build from main.

10. Follow the instructions on the Creating a PyPi Package page

11. Announce the release: