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¶
Check that
versioninpyproject.tomlis 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 tomain.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, novprefix – because the feedstock builds its source URL from it, and it must matchversioninpyproject.tomlexactly.Wait for the conda-forge bot to open a version-bump PR on the
ismip7-scalarsfeedstock, 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.