Release Process

1. Start preparing the PR that drafts the release notes. This involves manually scanning all of the merged and appropriately milestoned PRs with an “enhancement” label, so that we don’t miss mentioning new features. For other merged PRs and closed issues (i.e., bug fixes), the tools/gh_lists.py script will capture them in a raw list. The list of authors in the release notes may be populated by running tools/authors.py script over the appropriate commit range. If there are new authors in this release, you may also need to adjust .mailmap accordingly to avoid duplication, other issues. Try to add 2-3 new summary “highlights” at the top of the release notes for each release. Do not merge the release notes PR into main branch until you are ready to proceed with the release process proper.

2. Start preparing the PR to bump the main branch to the next version number, but DO NOT merge it until: the above release notes PR has been merged, the new maintenance branch has been pushed up. maintenance branches are named following this convention: maintenance/0.1.x for the 0.1.x release series, maintenance/0.2.x for the 0.2.x release series, and so on. This allows bug fixes to be backported to maintenance branches while the main branch continues to gain new features.

3. After pushing the new maintenance branch up, that branch may need backport PR(s) for dependency version pins (upper bounds to avoid future breaks), fixups to release notes, etc.

4. As our project is currently small with few consumers, we will not use release candidates at this time, and will proceed directly with feature releases. As a precaution, try to work in a Python environment with the minimum version of each dependency when performing the release process.

5. Adjust the version number to remove the trailing .dev0 in pyproject.toml.

6. Now create a release commit similar to i.e., REL: GFDL 0.1.0 release commit based on the current release version, but DO NOT push it yet.

7. Tag the release locally with git tag -s <v0.x.y> (the -s ensures the tag is signed–make sure you are properly setup for signing tags).

8. Continue with building release artifacts.

9. Since we are currently a pure Python project, go ahead and build the source distribution and binary (wheel) locally: python -m build. If that succeeds, go ahead and push the release commit to the GFDL repo.

10. Now, start uploading release artifacts (you may need to ask for appropriate permissions if you are a new release manager). For PyPI, upload first the portable wheel, and then the sdist. twine upload /path/to/*.whl and then twine upload /path/to/*.tar.gz. For the GitHub releases, use the GUI at lanl/GFDL to create a release and upload all release artifacts. At this stage you can push up the release tag so that it may be used for the GitHub release: git push origin v0.1.0.

11. Update the deployed documentation following the release.

12. For now, we will only announce the release within our small team by email with a short message and a copy of the release notes.

13. After the release is done, forward port relevant changes to release notes, build scripts, author name mapping, and tools scripts that were only made on the maintenance branch back to main.

14. Finally, after the release, create a PR against the maintenance branch to draft the release notes skeleton for the next bug fix release on that branch, and bump to the next y in the version number (0.x.y.dev0) in pyproject.toml.