Release a new version

Here is a short list of the actions to do for each new release.

1. Update the release notes

2. Make sure VERSION file version matches the name of the working version to be released. Do not include suffixes like alphaA, betaB, rcX …

Version format is expected to follow the following convention: M.m(.p) See https://packaging.python.org/guides/distributing-packages-using-setuptools/#standards-compliance-for-interoperability

3. Make sure version number is up-to-date in CITATION.cff and .zenodo.json files.

4. Handle all the issues associated for the related milestone, and close it.

5. Push develop branch.

   git checkout develop && git push
   

6. Wait for its pipeline to succeed. Go back and fix what needs fixing otherwise.

7. Merge develop branch into master

   git checkout master && git pull && git merge develop
   

8. Push master branch.

   git push
   

9 Create a git tag matching the desired version number.

This time, the tag version can include suffixes like alphaA, betaB, rcX …

If it doesn’t match the content of VERSION file, tagging shall be rejected by the reference_transaction git hook.

# in the case of pre-release versions:
git tag -a "${version}rc1"
# or the case the final versions:
git tag -a "${version}"
# Plus fill-in version information

10. Push the tag

git push --tags

Note

From there on, the CI will automatically take care of registering the source distribution (only; and not the wheel!) on PyPi as if we had manually run

# Prepare the packets for PyPi
python3 setup.py sdist

# Push to PyPi
python3 -m twine upload --repository pypi dist/S1Tiling-${version}*

11. For major and minor versions, create a branch named after this version. It will help to track issues patching of that version independently of work done on the next version, tracked in develop.

git checkout -b release-${version}
git push --set-upstream origin release-${version}

12. Go to github mirror, once the repository has been mirrored, to create a new release. This will automatically generate a new DOI on zenodo.

13. Go to the new zenodo release and update project metadata that cannot be set in CITATION.cff file.

14. Eventually, update VERSION file to the next expected version number. Never use any suffix in that file.

15. Announce the new release to the World.

A note on the management of version numbering

Version numbers are extracted as described in get_version() function.

s1tiling.libs._version.template = '{tag}'

Default version template value when on-tag.

s1tiling.libs._version.dev_template = '{tag}+{branch}{ccount}+git.{sha}'

Default version template value when there are uncommitted/untracked changes.

s1tiling.libs._version.dirty_template = '{tag}+{branch}{ccount}+git.{sha}+dirty'

Default version template value when there has been commits since last commit on VERSION file.

s1tiling.libs._version.get_version() → str

Overrides setuptools-git-versioning behaviour.

The overridden behaviour is as follow:

1. If there is a tag on the current commit,

   1. and if the tag is of the form “M.m(.p)(rcX|alphaX|betaX…)”, then return that tag;

   2. otherwise return {next_version_file content}+{tag}.

2. Otherwise, we assume tag = next_version (from VERSION file), then

   1. if there are uncommitted or untracked files, {dirty_template} is returned;

   2. if there have been commits since last commit on the next version file VERSION, {dev_template} is returned;

   3. otherwise {template} (i.e. content of the version file) is returned.

This implementation is a simplified and tailored version of setuptools_git_versioning.version_from_git() which is under MIT license