diff --git a/RELEASE.rst b/RELEASE.rst new file mode 100644 index 0000000000000000000000000000000000000000..760ee226c40c6e9a40dd7f3f124e2d8489eba99e --- /dev/null +++ b/RELEASE.rst @@ -0,0 +1,155 @@ +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 +---------------------------- +Check that there is an appropriate ``whatsnew`` file in ``doc/source/pre/whatsnew``. +This should be named as:: + + <major>.<minor>.<patch>.rst + +and 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. + + +Tag the release +############### +Make an *annotated*, *signed* tag for the release. The tag must have the semantic +versioning format:: + + v<major>.<minor>.<patch> + +Once the tag has been created, push it to Kwant Gitlab. + + +Post-tagging +############ +Pushing a new tag to Kwant Gitlab will kick off a few CI jobs, but there is +still some manual work to do. + + +Prepare the Debian package +-------------------------- + + +Gather the autobuilt packages from CI +------------------------------------- +CI automatically generates: + ++ HTML documentation ++ Zipped HTML documentation ++ PDF documentation ++ ``sdist`` package (for upload to PyPI) + +These can be found in the artifacts of the last CI job in the pipeline, +``gather release artifacts``. + + +Publish to the Kwant website +---------------------------- +To do the following you will need access to the webroots of ``downloads.kwant-project.org`` +and ``kwant-project.org``. Ask Christoph Groth if you need to be granted access. + +Take the tar archive in the ``dist`` directory of the CI artifacts and generate +a detached GPG signature:: + + gpg --armor --detach-sign kwant-<major>.<minor>.<patch>.tar.gz + +Take the archive and the ``.asc`` signature file that was just generated +and upload them to the ``kwant`` directory of ``downloads.kwant-project.org``. + +Take the zip archive and the PDF in the ``docs`` directory of the CI artifacts +and upload them to the ``doc`` directory of ``downloads.kwant-project.org``. +Point the symbolic links ``latest.zip`` and ``latest.pdf`` to these new files. + +Take the ``docs/html`` directory of the CI artifacts and upload them to:: + + doc/<major>.<minor>.<patch>/ + +on ``kwant-project.org``. Point the symbolic link ``<major>`` to this directory. + + +Publish to PyPI +--------------- +Install `twine <https://pypi.python.org/pypi/twine>` and use it to upload +the tar archive in the ``sdist`` directory of the Ci artifacts downloaded +in the previous step:: + + twine upload --sign -u <PyPI username> -p <PyPI password> sdist/* + +the ``--sign`` flag signs the uploaded package with your default GPG key. +Ask Christoph Groth for the Kwant PyPI credentials. + + +Publish to Launchpad +-------------------- + + + +Publish to Conda forge +---------------------- +Conda forge automates build/deploy by using CI on Github repositoried containing +recipes for making packages from their source distributions. + +Fork the `Kwant feedstock <https://github.com/conda-forge/kwant-feedstock>` +repository and edit the file ``recipe/meta.yml``. Correctly set the ``version`` +at the top of the file. Set the ``sha256`` string in the ``source`` section +near the top of the file to the SHA256 hash of the kwant source distribution +that was uploaded to ``downloads.kwant-project.org``. This can be found by:: + + sha256sum kwant-<major>.<minor>.<patch>.tar.gz + +Now commit these changes and open a pull request on the Kwant feedstock +repository that includes your change. Ask Bas Nijholt or Joseph Weston +to review and accept the pull request, so that Kwant will be rebuilt. + + +Announce the release +-------------------- +Write a short post summarizing the highlights of the release on the +`Kwant website <https://gitlab.kwant-project.org/kwant/website>`, then +post this to the mailing list kwant-discuss@kwant-project.org. + + +Working towards the next release +################################ +After finalizing a release, a new ``whatsnew`` file should be created for +the *next* release, and this addition should be committed and tagged as:: + + <new major>.<new minor>.<new patch>a0 + +This tag should be pushed to Kwant Gitlab, and a new milestone for the next +release should be created.