Cutting a release

IDAES Release Engineering Cheat Sheet

Here's where all the IDAES release eng / dev ops secrets are kept...

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

Creating a new IDAES 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 ./idaes/ver.py on this release branch (to version used above)

3. Update install_requires in setup.py versions on release branch for the pyomo and pyutilib versions to grab from PyPi. It should look something like:

       "pyutilib>=6.0.0",
       "pyomo>=5.7.1, ==5.7.*",
   

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

5. Create the new release in github on the idaes-pse 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. (python -c "from idaes.ver import __version__ as v; print(v)" will show an extra +<hash> here because we do some insane reading of .git/HEAD references).

7. Now on main, if not already done, change the same idaes/ver.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. Also, make sure that the changes made to setup.py are propagated on main.

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. Build docs in examples-pse repo. For more information, refer to the documentation specific to examples-pse available at Cutting a release of examples-pse.

12. Announce the release:

• Email to idaes-leadership, idaes-users, idaes-stakeholder lists
• Update news page on idaes.org

These steps might need to be repeated if a new release candidate is needed, or the final release differs from the release candidate. In that case, if a new changes on main need to be brought into the release branch (i.e. new PRs) follow these instructions on how to merge specific PRs into release branch from main.