RELEASE.rst

Making a Kwant release

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

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 is up-to-date

The following command shows the number of commits per author since the last annotated tag:

t=$(git describe --abbrev=0); echo Commits since $t; git shortlog -s $t..

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 html latex SPHINXOPTS='-A website_deploy=True -n -W' REFNAME="<version>"
cd doc/build/latex
make all-pdf

Then create a zipped version of the HTML documentation and name the PDF consistently:

zip -r docs/build/kwant-doc-<version>.zip docs/build/docs/build/html
mv docs/build/latex/kwant.pdf docs/build/kwant-doc-<version>.pdf

Clone the repository of the Kwant conda-forge package

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

Clone the "Kwant feedstock" repository and go into its root directory. If you keep the Kwant source in "src/kwant", a good location for the Conda package repository is "src/conda-forge/kwant":

cd ~/src
mkdir conda-forge
cd conda-forge
git clone https://github.com/conda-forge/kwant-feedstock kwant
cd kwant

Rename the default remote to upstream:

git remote rename origin upstream

Create a new version of the Kwant conda-forge package

Edit the file recipe/meta.yml. Correctly set the version at the top of the file to the version of this release. Set the sha256 string in the source section near the top of the file to the SHA256 hash of the kwant source tarball that we previously created. You can find the SHA256 hash by running openssl sha256 <filename> on Linux and Mac OSX.

Commit your changes.

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:

git remote add upstream_repo ~/src/kwant

Make sure that:

git config --get user.name
git config --get user.email

show correct information.