@@ -14,7 +14,7 @@ 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>`

+`milestone <https://gitlab.kwant-project.org/kwant/kwant/milestones>`_

 have been resolved. Any unresolved issues should have their milestone

 bumped.

@@ -26,7 +26,7 @@ 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 executes.

+conda package and verify that it, too, succeeds.

 Inspect the documentation

@@ -42,17 +42,17 @@ Check that there are no glaring deficiencies.

 Update the ``whatsnew`` file

 ----------------------------

-For each new mior release, check that there is an appropriate ``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 after any major features were released, if not

-then you can see what commits were introduced since the last release using

+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

-milestons and get an idea of what was introduced from there.

+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.

@@ -82,10 +82,6 @@ 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>"

@@ -93,11 +89,11 @@ Make an *annotated*, *signed* tag for the release. The tag must have the name::

 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!

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

-Build a source taball and inspect it

+Build a source tarball and inspect it

+-------------------------------------

     ./setup.py sdist

@@ -110,6 +106,54 @@ in /tmp and inspect that builds in isolation and that the tests run::

     ./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

 ------------------------------------------------

@@ -178,7 +222,7 @@ 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

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

     gbp pq rebase

@@ -210,7 +254,8 @@ 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.

+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

@@ -264,7 +309,7 @@ Another example: build source package only::

     gbp buildpackage --git-export-dir=/tmp -S

-Build packports for the current Debian stable

+Build backports for the current Debian stable

 ---------------------------------------------

 Create a changelog entry for the backport::

@@ -286,7 +331,7 @@ Publish the release

 If the Debian packages build correctly that means that all tests pass both on

 i386 and amd64, and that no undeclared dependencies are needed.  We can be

-reasonable sure that the release is ready to be published.

+reasonably sure that the release is ready to be published.

 git

 ---

@@ -298,7 +343,9 @@ Push the tag to the official Kwant repository::

 PyPI

 ----

-PyPI (this requires a file ~/.pypirc with a vaild username and password)::

+Install `twine <https://pypi.python.org/pypi/twine>`_ and run the following

+(this requires a file ~/.pypirc with a valid username and password: ask

+Christoph Groth to add you as a maintainer on PyPI, if you are not already)::

     twine upload -s dist/kwant-<version>.tar.gz

@@ -310,10 +357,11 @@ PyPI.

 Kwant website

 -------------

-The tarball and its signature (generated by the twine command above) should be

-also made available on the website::

+The following requires ssh access to ``kwant-project.org`` (ask Christoph

+Groth). The tarball and its signature (generated by the twine command above) should be

+uploaded to the downloads section of the website::

-    scp dist/kwant-<version>.tar.gz* kwant-website-downloads:downloads/kwant

+    scp dist/kwant-<version>.tar.gz* kwant-project.org:webapps/downloads/kwant

 Debian packages

 ---------------

@@ -323,8 +371,8 @@ Go to the Debian packaging repository and push out the changes::

     git push --tags origin master upstream

 Now the Debian packages that we built previously need to be added to the

-repository of Debian packages on the Kwant website.  So far this the full

-version of this repository is kept on Christoph Groth's machine, so this

+repository of Debian packages on the Kwant website.  So far the full

+version of this repository is kept on Christoph Groth's machine, so these

 instructions are for reference only.

 Go to the reprepro repository directory and verify that the configuration file

@@ -365,7 +413,7 @@ sure to use the appropriate <dist>: for the above configuratoin file either

 Once all the packages have been added, upload the repository::

-    rsync -avz --delete dists pool wfw:webapps/downloads/debian

+    rsync -avz --delete dists pool kwant-project.org:webapps/downloads/debian

 Ubuntu packages

 ---------------

@@ -374,6 +422,7 @@ Packages for Ubuntu are provided as a PPA (Personal Package Archive):

 https://launchpad.net/~kwant-project/+archive/ubuntu/ppa

 Make sure ~/.dput.cf has something like this::

+

     [ubuntu-ppa-kwant]

     fqdn = ppa.launchpad.net

     method = ftp

@@ -382,6 +431,7 @@ Make sure ~/.dput.cf has something like this::

     allow_unsigned_uploads = 0

 We will also use the following script (prepare_ppa_upload)::

+

     #!/bin/sh

     if [ $# -eq 0 ]; then

@@ -417,93 +467,53 @@ Now the changes files are "put" to start the build process on the PPA servers::

     dput ubuntu-ppa-kwant *~*.changes

-Gather the autobuilt packages from CI

-

-(This section needs to be updated.  Using the sdist package as generated by

-PyPI requires pushing the tag to gitlab and as such is incompatible with doing

-the Debian packaging with an unpublished tag.)

-

-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

-

-(This section needs to be updated.  The twine tool creates the signature file

-during the upload.)

-

-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``.

+Conda forge

+-----------

+This step requires a GitHub account, as Conda forge packages are autobuilt

+from repositories hosted on GitHub.

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

+Fork the `Kwant feedstock <https://github.com/conda-forge/kwant-feedstock>`_

+repository and add your fork as a remote to the copy that you previously cloned::

-Take the ``docs/html`` directory of the CI artifacts and upload them to::

+    cd ~/conda-forge/kwant

+    git remote add myfork https://github.com/<your-gh-username>/kwant-feedstock

-    doc/<major>.<minor>.<patch>/

+Push the changes that you previously commited to your fork::

-on ``kwant-project.org``. Point the symbolic link ``<major>`` to this directory.

+    git push myfork master

+Open a pull request to Kwant feedstock repository. Ask Bas Nijholt or

+Joseph Weston to review and accept the pull request.

-Publish to PyPI

-

-(This also needs to be updated.)

-

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

+Documentation

+-------------

+The following requires ssh access to  ``kwant-project.org``.

+Ask Christoph Groth if you need to be granted access.

+Upload the zipped HTML and PDF documentation::

-Publish to Launchpad

+    scp doc/build/kwant-doc-<version>.zip kwant-project.org:webapps/downloads/doc

+    scp doc/build/kwant-doc-<version>.pdf kwant-project.org:webapps/downloads/doc

+Point the symbolic links ``latest.zip`` and ``latest.pdf`` to these new files::

+    ssh kwant-project.org "cd webapps/downloads/doc; ln -s kwant-doc-<version>.zip latest.zip"

+    ssh kwant-project.org "cd webapps/downloads/doc; ln -s kwant-doc-<version>.pdf latest.pdf"

-Publish to Conda forge

+Then upload the HTML documentation for the main website::

-Conda forge automates build/deploy by using CI on Github repositoried containing

-recipes for making packages from their source distributions.

+    rsync -rlv --delete doc/build/html/* kwant-project.org:webapps/kwant/doc/<short-version>

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

+where in the above ``<short-version`` is just the major and minor version numbers.

-    sha256sum kwant-<major>.<minor>.<patch>.tar.gz

+Finally point the symbolic link ``<major-version>`` to ``<short-version>``::

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

+    ssh kwant-project.org "cd webapps/kwant/doc; ln -s <major> <short-version>"

 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