The procedure applies to both ixmp and message_ix.
The ixmp release must be processed before message_ix.
The person (or persons) processing the release needs the following authorizations:
In the below:
<version>stands for the full version number, e.g.
1.2.0. Always include all three parts: major, minor, and patch, i.e.
1.2. Look very carefully to see when
<version>should be used.
<upstream>stands for your local name for the Git remote that is the IIASA Github repository.
Update these instructions. Keep them current with actual practice.
Handle deprecations. You can find these by searching the code base for “deprecat”.
A deprecation always involves two versions: (1) the version in which the item “is [marked as] deprecated”, and (2) the version in which the item is removed. These must always be separated by at least one major version. For instance, an item marked as deprecated in v2.1 can be removed as of v3.0; an item marked as deprecated in v3.0 can be removed in v4.0, or later, e.g. in v5.0.
Mark any new deprecations. Explicitly state the version when the removal is targeted, so that users can adjust their code.
Remove any items targeted for removal in this release.
This can be done at any point, and should be done before the release prep begins. For instance, a feature marked as deprecated in v2.0 should be removed before 3.0 is released. But may also be removed from the
masterbranch immediately after 2.0.0 is released. This is preferred, because it forces tutorials, user code, etc. to stay ahead of deprecations.
(message_ix only) Edit
setup.cfg, updating the
install_requiresline for ixmp as necessary.
Each version of message_ix depends on a minimum version of ixmp. message_ix must not depend on or use deprecated features of ixmp; it should remain compatible with earlier versions of ixmp, where possible.
Check continuous integration. Any failures in (4) or (5) must be corrected before releasing.
Check https://readthedocs.com/projects/iiasa-energy-program-message-ix/builds/ (or ixmp) to ensure that the docs build is passing.
If necessary, make and merge ≥1 PR(s) to address (1–5).
Create a new branch:
$ git checkout -v release/X.Y.Z
Comment the heading “Next release”, and insert below it:
A commented “All changes” sub-heading (
A ReST anchor with the version number.
Another heading (
===) below it, with the version number and date
Add a short text description summarizing the release.
If necessary, add a subsection “Migration notes” explaining to users how to adjust to changes in the release.
For example, the top of the file should look like:
Next release ============ All changes ----------- - Description of a change (:pull:`9999`).
.. Next release .. ============ .. All changes .. ----------- .. _v99.98.0: v99.98.0 (2035-10-12) ===================== Here is a description of the release. Migration notes --------------- Here is guidance on how to adjust to the release. All changes ----------- - Description of a change (:pull:`9999`).
Build the docs locally to ensure any ReST markup in these additions renders correctly.
Make a commit with a message like “Mark v<version> in release notes”.
Tag the release candidate version, i.e. with a
rcNsuffix, and push:
$ git tag vX.Y.ZrcN $ git push --tags <upstream> release/X.Y.Z
Open a PR with the title “Release vX.Y.Z” using this branch. Check:
at https://github.com/iiasa/message_ix/actions/workflows/publish.yaml (or ixmp) that the workflow completes: the package builds successfully and is published to TestPyPI.
The package can be downloaded, installed and run.
The README is rendered correctly.
Address any warnings or errors that appear, if necessary through ≥1 new commit(s). Then continue from step (4), incrementing the release candidate number, e.g. from
Merge the PR using the ‘rebase and merge’ method.
(optional) Tag the release itself and push:
$ git tag v<version> $ git push --tags origin main
This step (but not step (4)) can be performed directly on GitHub; see (8), next.
For the description, provide a link to the section in the “What’s New” page of the documentation that corresponds to the new release, using the anchor added in (3), above. For example:
See [“What's New”](https://docs.messageix.org/en/stable/whatsnew.html#v99-98-0) in the documentation for a list of all changes.
Check at https://github.com/iiasa/message_ix/actions/workflows/publish.yaml (or ixmp) and https://pypi.org/project/message-ix/ (or ixmp) that the distributions are published.
Update on conda-forge. A PR should automatically be opened by a bot after the GitHub release (sometimes this takes from 30 minutes to several hours).
Confirm that any new dependencies are added. The minimum versions in
meta.yamlshould match the versions in
Ensure that tests pass and complete any other checklist items.
Merge the PR.
Check that the new package version appears on conda-forge. This may take up to several hours.
Announce the release(s) on our mailing list/Google group and/or on Twitter. Copy the text from the What’s New page of the built documentation.