RELEASE.rst

Making a Kwant release

This document guides a contributor through creating a release of Kwant.

Create a release issue

Use the correct issue template, adjust it if necessary.

Preflight checks

The following checks should be made before tagging the release.

Check that all issues are resolved

Check that all the issues and merge requests for the appropriate milestone have been resolved. Any unresolved issues should have their milestone bumped.

Ensure that all tests pass

For major and minor releases we will be tagging the master branch. For patch releases, the stable branch. This should be as simple as verifying that the latest CI pipeline succeeded, however in stable branch also manually trigger CI task of building the conda package and verify that it, too, succeeds.

Inspect the documentation

If the CI pipeline succeeded, then the latest docs should be available at:

https://test.kwant-project.org/doc/<branch name>

Check that there are no glaring deficiencies.

Update the whatsnew file

For each new minor release, check that there is an appropriate whatsnew file in doc/source/pre/whatsnew. This should be named as:

<major>.<minor>.rst

and referenced from doc/source/pre/whatsnew/index.rst. It should contain a list of the user-facing changes that were made in the release. With any luck this file will have been updated at the same time as a feature was implemented, if not then you can see what commits were introduced since the last release using git log. You can also see what issues were assigned to the release's milestones and get an idea of what was introduced from there.

Starting with Kwant 1.4, we also mention user-visible changes in bugfix releases in the whatsnew files.

Verify that AUTHORS.rst and .mailmap are up-to-date

The following command shows if there are any committers that are missing from AUTHORS.rst:

git shortlog -s | sed -e "s/^ *[0-9\t ]*//"| xargs -i sh -c 'grep -q "{}" AUTHORS.rst || echo "{}"'

If it outputs anything, then either add the new contributors to the list, or add new identities of old contributors to the .mailmap

Make a release, but do not publish it yet

Various problems can surface only during the process of preparing a release and make it necessary to fix the codebase. It would be a pity to have to succeed the freshly released version by a minor release just to correct a glitch that was detected too late. Therefore it is a good idea to pursue the release as far as possible without announcing it, such that it can be undone and corrected if necessary. In the past tests that failed on the x86-32 architecture and wrongly declared dependencies have been detected in this way.

Tag the release

Make an annotated, signed tag for the release. The tag must have the name:

git tag -s v<version> -m "version <version>"

Be sure to respect the format of the tag name (leading "v", e.g. "v1.2.3"). The tag message format is the one that has been used so far.

Do not yet push the tag anywhere; it might have to be undone!

Build a source tarball and inspect it

./setup.py sdist

This creates the file dist/kwant-<version>.tar.gz. It is a good idea to unpack it in /tmp and inspect that builds in isolation and that the tests run:

cd /tmp
tar xzf ~/src/kwant/dist/kwant-<version>.tar.gz
cd kwant-<version>
./setup.py test

Build the documentation

Building the documentation requires 'sphinx' and a Latex installation. First build the HTML and PDF documentation:

./setup.py build
make -C doc realclean
make -C doc html latex
make -C doc/build/latex all-pdf

Then create a zipped version of the HTML documentation and name the PDF consistently, storing them, for example, in the "dist" directory along with the source tarballs:

version=$(git describe | sed 's/^v//') # Assumes that we are on a tag.
ln -s `pwd`/doc/build/html /tmp/kwant-doc-$version
(cd /tmp/; zip -r kwant-doc-$version.zip kwant-doc-$version)
mv /tmp/kwant-doc-$version.zip dist
mv doc/build/latex/kwant.pdf dist/kwant-doc-$version.pdf

Finally, rebuild the documentation for the website (including the web analysis javascript code):

make -C doc html SPHINXOPTS='-A website_deploy=True -n -W'

Clone the repository of the Kwant Debian package

This step needs to be performed only once. The cloned repository can be reused for subsequent releases.

Clone the "kwant-debian" repository and go into its root directory. If you keep the Kwant source in "src/kwant", a good location for the Debian package repository is "src/debian/kwant". The packaging process creates many files that are placed into the parent directory of the packaging repository, hence having an additional directory level ("src/debian") is a good way to keep these files separate:

mkdir debian
cd debian
git clone ssh://git@gitlab.kwant-project.org:443/kwant/debian-kwant.git kwant
cd kwant

Create a local upstream branch:

git branch upstream origin/upstream

Add a remote for the repository that contains the previously created tag: