Releasing

This page is for maintainers – those with write access to the main repository. If you are contributing from a fork, nothing here is yours to do; open the pull request and a maintainer will fold it into the next release.

Users get the tools from conda-forge, and conda-forge builds from a tag. Anything on main that has not been tagged therefore does not exist as far as they are concerned.

So release often: whenever a change reaches main that a user would notice. That is deliberately a low bar: a change to how a scalar is computed or to a value the code defines, a new or altered command-line option, a change to the output filenames or CSV columns, a bug fix, or a widened dependency range. Releases are cheap; someone chasing a discrepancy against a source checkout that turns out to be six months of untagged changes is not. Refactorings, tests, CI and documentation-only changes need no release, though there is no harm in folding them into the next one.

Version numbers

Versions follow semantic versioning:

  • patch (0.1.0 → 0.1.1): a fix that changes no output.

  • minor (0.1.0 → 0.2.0): a new command, option or option value, a change to how a scalar is computed, or a dependency range widened.

  • major (0.1.0 → 1.0.0): a change to the output layout, the filenames or the CSV columns, or an option removed or renamed.

While the version is 0.x, a change that would be major bumps the minor version instead, as semantic versioning allows.

A change to how a scalar is computed is never a patch, and its release notes say which scalars it affects. If a value the code defines changed – a constant such as the ocean area, a default such as a reference year, or the pairing in the CORE table – they also give the old and new value. How far a given submission’s numbers move depends on the submission, so the notes do not try to say. People compare these numbers across submissions; a silent change to them is worse than no release at all.

A pull request with a change a user would notice should bump version in pyproject.toml itself, by the smallest step that covers it. If main already has an unreleased bump that covers it, leave it. That way main always carries the version its next release will have, and cutting the release is only the tag.

The relationship with isschecker

This package reads the ISMIP7 data request out of isschecker at runtime (see Where the conventions come from), which has two consequences for releases.

A data request change is released by isschecker, not here. If a variable’s standard_name or long_name is corrected upstream, updating isschecker is enough; this package needs no release at all. That is the point of not keeping a copy.

A change of shape does need a release here — a renamed column makes the lookup fail loudly, and the fix is a change here plus the isschecker floor raised to the version that has it.

Cutting a release

  1. Check that version in pyproject.toml is ahead of the last release. The pull requests since then should have bumped it (see Version numbers); if none did, bump it now and merge that to main.

  2. Draft a new GitHub release against main. In the tag field, type the new version and choose Create new tag on publish, so that publishing the release creates the tag: one action, and the two can never disagree about which commit they point at. Write notes saying what changed for users, then publish.

    The tag is the bare version number – 0.2.0, no v prefix – because the feedstock builds its source URL from it, and it must match version in pyproject.toml exactly.

  3. Wait for the conda-forge bot to open a version-bump PR on the ismip7-scalars feedstock, usually within a few hours. Review and merge it; the package appears on conda-forge shortly after the build finishes. Merging it needs write access to the feedstock, which is separate from write access here – see Maintaining the feedstock.

If the release changed the dependency ranges, edit the feedstock PR before merging so that the run: requirements in recipe/recipe.yaml match pyproject.toml and ismip7_scalars_env.yml – the bot updates the version and hash, not the requirements. Those three lists are the same constraints written down three times, and it is worth checking them against one another at each release.

Confirming what was published

Optionally, confirm what was published rather than assuming it:

conda create -n ismip7-scalars-test -c conda-forge --override-channels \
    ismip7-scalars pytest
conda activate ismip7-scalars-test
ismip7-scalars --version    # should print the version you tagged
cd $(mktemp -d) && pytest -v /path/to/ismip7-scalar-processing/tests

Run that from a checkout of the tag, not of main: the tests come from the source tree while the package comes from conda-forge, so with main checked out any change made since the tag shows up as a test failure that says nothing about the release.

It is optional because of the wait. A merged feedstock PR does not put the package within reach immediately: the build has to finish, and the result then takes roughly an hour to propagate. Until it has, conda create either cannot find the new version or reports the old one, and neither means anything is wrong. So this is not a step to sit and retry – come back to it later in the day, or skip it. CI already runs the full suite against the tagged source at both ends of every dependency range, and the feedstock runs the import, each command’s --help and the test suite before publishing at all.

Maintaining the feedstock

The conda-forge package is built by its own repository, separate from this one, with its own list of maintainers – being a maintainer here does not make you one there. Only feedstock maintainers can merge the bot’s version-bump PRs, so a release stalls if nobody available has that access. It is worth having more than one of us on the list.

The list lives in the recipe itself, under extra: recipe-maintainers:. To be added, open an issue on the feedstock titled:

@conda-forge-admin, please add user @your-github-username

A bot then opens a PR adding you, which an existing feedstock maintainer merges. GitHub will email you an invitation to the feedstock’s team in the conda-forge organization; you have to accept it, or the merge has given you nothing. This is conda-forge’s documented mechanism, described under Updating the maintainer list; leave the bot’s PR alone rather than editing it, since it is built to skip a package rebuild.

The conda-forge maintainer documentation covers the rest. Very little of it is needed for a package as simple as this one – a pure-Python noarch recipe whose releases are usually nothing more than a version and a hash.