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 <https://gitlab.kwant-project.org/kwant/kwant/milestones> have been resolved. Any unresolved issues should have their milestone bumped.

Ensure that all tests pass

This should be as simple as verifying that the latest CI pipeline succeeded. For major and minor releases we will be tagging the master branch. For patch releases, the stable branch.

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 mior 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 after any major features were released, 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 milestons 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

A particularly good way to expose hidden problems is building Debian packages using an isolated minimal build environment (cowbuilder). This approach is described here.

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 taball 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

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.

Release a new version of the Kwant Debian package

Fetch packaging work (from origin) and the git tag created above (from upstream_repo) into the packaging repo:

git fetch --all

Make sure that the branches master and upstream are up-to-date:

git checkout upstream
git merge --ff-only origin/upstream
git checkout master
git merge --ff-only origin/master

Debian packages may include "quilt" patches that are applied on top of the pristine tarball. The tool gbp pq manages these patches as a git branch patch-queue/master. Execute the following commands to (re)create that branch based on the patches in ``debian/patches:

gbp pq --force import
gbp checkout master

Now it is time to import the new source code. There are two options. If, as recommended above, the tarball of the new version has not been made public yet, it must be imported as follows:

gbp import-orig ~/src/kwant/dist/kwant-<version>.tar.gz

Alternatively, the following commands will import the newest version from PyPI:

uscan --report      # This will report if a newer version exists on PyPI
gbp import-orig --uscan

Now it is time to review the patch queue. Rebase and checkout the patch-queue/master branch using

gbp pq rebase

As ususal, the rebase might require manual intervention. Once done, review all the commits of the patch-queue/master branch. Are all patches still needed, should any be removed? When done (even if no changes were needed), recreate the files in debian/patches using:

gbp pq export

If git diff reports any changes, be sure to commit them.

Now is the right moment to verify and modify the packaging information inside the debian/ directory. For example, are the dependencies and versions stated in debian/control up-to-date?

When all changes are commited, it is time to finalize by updating the Debian changelog file. Add a point "New upstream release" if there was one, and describe any other changes to the Debian packaging:

DEBEMAIL=<your-email> gbp dch -R --commit --distribution testing

Now verify that the package builds with:

git clean -i
gbp buildpackage

This is not how the package should be built for distribution. For that, see the following two sections.

If problems surface that require changing the packaging, undo the changelog commit, modify the packaging, and re-iterate. If the problems require fixing Kwant, you will have to go back all the way to recreating the source tarball. If the version to be packaged has been released publicly already, this will require a new bugfix version.

Setup git-pbuilder to build Debian packages

Pbuilder is a tool to build Debian packages in an isolated chroot. This allows to verify that the package indeed only has the declared dependencies. It also allows to cross-build packages for i386 on amd64.

The following describes how to setup git-pbuilder, see also https://wiki.debian.org/git-pbuilder. This procedure needs to be executed only once for a Debian system.

Install the Debian package git-buildpackage.

As root, add the following lines to /etc/sudoers or /etc/sudoers.d/local

Cmnd_Alias BUILD = /usr/sbin/cowbuilder

and

user ALL = SETENV: BUILD

Now create pbuilder images. In the following, replace <dist> by the current Debian testing codename, e.g. "buster":

ARCH=i386 DIST=<dist> git-pbuilder create
ARCH=amd64 DIST=<dist> git-pbuilder create

If the packages to be built have special dependencies, use the trick described in https://wiki.debian.org/git-pbuilder#Using_Local_Packages