Release and Distribution¶

Updating the Changelog¶

This needs to be done no matter what type of release is being made.

1. Create a new branch to use to make a pull request.

2. Write the changelog for this version in doc/changelog.rst. Look at recent entries in that file to get a feel for the style. In general, the format is one or two paragraphs written in regular prose describing the major new features of the version, and anything that needs special attention. After that, in suitable headings, list all the changes and who made them. Headings you may want to have include “Features”, “Improvements”, “Bug Fixes”, “Deprecations”, “Removals” and “Developer Changes”, but feel free to use anything sensible.

3. Make a pull request on the main qutip/qutip repository with this changelog, and get other members of the admin team to approve it.

4. Merge this into master.

Now jump to release if you are making a major or minor release, or bugfix if you are only fixing bugs in a previous release.

Create a New Minor or Major Release¶

This involves making a new branch to hold the release and adding some commits to set the code into “release” mode. This release should be done by branching directly off the master branch at its current head.

1. On your machine, make sure your copy of master is up-to-date (git checkout master; git pull upstream master). This should at least involve fetching the changelog PR that you just made. Now create a new branch off a commit in master that has the state of the code you want to release. The command is git checkout -b qutip-<major>.<minor>.X, for example qutip-4.7.X. This branch name will be public, and must follow this format.

2. Push the new branch (with no commits in it relative to master) to the main qutip/qutip repository (git push upstream qutip-4.7.X). Creating a branch is one of the only situations in which it is ok to push to qutip/qutip without making a pull request.

3. Create a second new branch, which will be pushed to your fork and used to make a pull request against the qutip-<major>.<minor>.X branch on qutip/qutip you just created. You can call this branch whatever you like because it is not going to the main repository, for example git checkout -b prepare-qutip-4.7.0.

4. • Change the VERSION file to contain the new version number exactly, removing the .dev suffix. For example, if you are releasing the first release of the minor 4.7 track, set VERSION to contain the string 4.7.0. (Special circumstances: if you are making an alpha, beta or release candidate release, append a .a<n>, .b<n> or .rc<n> to the version string, where <n> is an integer starting from 0 that counts how many of that pre-release track there have been.)

   • Edit setup.cfg by changing the “Development Status” line in the classifiers section to

     Development Status :: 5 - Production/Stable
     

   Commit both changes (git add VERSION setup.cfg; git commit -m "Set release mode for 4.7.0"), and then push them to your fork (git push -u origin prepare-qutip-4.7.0)

5. Using GitHub, make a pull request to the release branch (e.g. qutip-4.7.X) using this branch that you just created. You will need to change the “base branch” in the pull request, because GitHub will always try to make the PR against master at first. When the tests have passed, merge this in.

6. Finally, back on master, make a new pull request that changes the VERSION file to be <next-expected-version>.dev, for example 4.8.0.dev. The “Development Status” in setup.cfg on master should not have changed, and should be

   Development Status :: 2 - Pre-Alpha
   

   because master is never directly released.

You should now have a branch that you can see on the GitHub website that is called qutip-4.7.X (or whatever minor version), and the state of the code in it should be exactly what you want to release as the new minor release. If you notice you have made a mistake, you can make additional pull requests to the release branch to fix it. master should look pretty similar, except the VERSION will be higher and have a .dev suffix, and the “Development Status” in setup.cfg will be different.

You are now ready to actually perform the release. Go to deploy.

Create a Bug Fix Release¶

In this you will modify an already-released branch by “cherry-picking” one or more pull requests that have been merged to master (including your new changelog), and bump the “patch” part of the version number.

1. On your machine, make sure your copy of master is up-to-date (git checkout master; git pull upstream master). In particular, make sure the changelog you wrote in the first step is visible.

2. Find the branch of the release that you will be modifying. This should already exist on the qutip/qutip repository, and be called qutip-<major>.<minor>.X (e.g. qutip-4.6.X). If you cannot see it, run git fetch upstream to update all the branch references from the main repository. Checkout a new private branch, starting from the head of the release branch (git checkout -b prepare-qutip-4.6.1 upstream/qutip-4.6.X). You can call this branch whatever you like (in the example it is prepare-qutip-4.6.1), because it will only be used to make a pull request.

3. Cherry-pick all the commits that will be added to this release in order, including your PR that wrote the new changelog entries (this will be the last one you cherry-pick). You will want to use git log to find the relevant commits, going from oldest to newest (their “age” is when they were merged into master, not when the PR was first opened). The command is slightly different depending on which merge strategy was used for a particular PR:

   • “merge”: you only need to find one commit though the log will have included several; there will be an entry in git log with a title such as “Merge pull request #1000 from <…>”. Note the first 7 characters of its hash. Cherry-pick this by git cherry-pick --mainline 1 <hash>.

   • “squash and merge”: there will only be a single commit for the entire PR. Its name will be “<Name of the pull request> (#1000)”. Note the first 7 characters of its hash. Cherry-pick this by git cherry-pick <hash>.

   • “rebase and merge”: this is the most difficult, because there will be many commits that you will have to find manually, and cherry-pick all of them. Go to the GitHub page for this PR, and go to the “Commits” tab. Using your local git log (you may find git log --oneline useful), find the hash for every single commit that is listed on the GitHub page, in order from oldest to newest (top-to-bottom in the GitHub view, which is bottom-to-top in git log). You will need to use the commit message to do this; the hashes that GitHub reports will probably not be the same as how they appear locally. Find the first 7 characters of each of the hashes. Cherry-pick these all in one go by git cherry-pick <hash1> <hash2> ... <hash10>, where <hash1> is the oldest.

   If any of the cherry-picks have merge conflicts, first verify that you are cherry-picking in order from oldest to newest. If you still have merge conflicts, you will either need to manually fix them (if it is a very simple fix), or else you will need to find which additional PR this patch depends on, and restart the bug fix process including this additional patch. This generally should not happen if you are sticking to very small bug fixes; if the fixes had far-reaching changes, a new minor release may be more appropriate.

4. Change the VERSION file by bumping the last number up by one (double-digit numbers are fine, so 4.6.10 comes after 4.6.9), and commit the change.

5. Push this branch to your fork, and make a pull request against the release branch. On GitHub in the PR screen, you will need to change the “Base” branch to qutip-4.6.X (or whatever version), because GitHub will default to making it against master. It should be quite clear if you have forgotten to do this, because there will probably be many merge conflicts. Once the tests have passed and you have another admin’s approval, merge the PR.

You should now see that the qutip-4.6.X (or whatever) branch on GitHub has been updated, and now includes all the changes you have just made. If you have made a mistake, feel free to make additonal PRs to rectify the situation.

You are now ready to actually perform the release. Go to deploy.

Build and Deploy¶

This is handled entirely by a GitHub Action. Go to the “Actions” tab at the top of the QuTiP code repository. Click on the “Build wheels, optionally deploy to PyPI” action in the left-hand sidebar. Click the “Run workflow” dropdown in the header notification; it should look like the image below.

• Use the drop-down menu to choose the branch or tag you want to release from. This should be called qutip-4.5.X or similar, depending on what you made earlier. This must never be master.

• To make the release to PyPI, type the branch name (e.g. qutip-4.5.X) into the “Confirm chosen branch name […]” field. You may leave this field blank to skip the deployment and only build the package.

• (Special circumstances) If for some reason you need to override the version number (for example if the previous deployment to PyPI only partially succeeded), you can type a valid Python version identifier into the “Override version number” field. You probably do not need to do this. The mechanism is designed to make alpha-testing major upgrades with nightly releases easier. For even a bugfix release, you should commit the change to the VERSION file.

• Click the lower “Run workflow” to perform the build and deployment.

At this point, the deployment will take care of itself. It should take between 30 minutes and an hour, after which the new version will be available for install by pip install qutip. You should see the new version appear on QuTiP’s PyPI page.

Download Built Files¶

When the build is complete, click into its summary screen. This is the main screen used to both monitor the build and see its output, and should look like the below image on a success.

The built binary wheels and the source distribution are the “build artifacts” at the bottom. You need to download both the wheels and the source distribution. Save them on your computer, and unzip both files; you should have many wheel qutip-*.whl files, and two sdist files: qutip-*.tar.gz and qutip-*.zip. These are the same files that have just been uploaded to PyPI.

Monitoring Progress (optional)¶

While the build is in progress, you can monitor its progress by clicking on its entry in the list below the “Run workflow” button. You should see several subjobs, like the completed screen, except they might not yet be completed.

The “Verify PyPI deployment confirmation” should get ticked, no matter what. If it fails, you have forgotten to choose the correct branch in the drop-down menu or you made a typo when confirming the correct branch, and you will need to restart this step. You can check that the deployment instruction has been understood by clicking the “Verify PyPI deployment confirmation” job, and opening the “Compare confirmation to current reference” subjob. You will see a message saying “Built wheels will be deployed” if you typed in the confirmation, or “Only building wheels” if you did not. If you see “Only building wheels” but you meant to deploy the release to PyPI, you can cancel the workflow and re-run it after typing the confirmation.

Copying New Files¶

You only need to copy in new documentation to the website repository. Do not copy the .whl, .tar.gz or .zip files into the git repository, because we can access the public links from the GitHub release stage, and this keeps the website .git folder a reasonable size.

For all releases move (no new docs) or copy (for new docs) the qutip-doc-<MAJOR>.<MINOR>.pdf into the folder downloads/<MAJOR>.<MINOR>.<MICRO>.

The legacy html documentation should be in a subfolder like

docs/<MAJOR>.<MINOR>

For a major or minor release the previous version documentation should be moved into this folder.

The latest version HTML documentation should be the folder

docs/latest

For any release which new documentation is included - copy the contents qutip/doc/_build/html into this folder. Note that the underscores at start of the subfolder names will need to be removed, otherwise Jekyll will ignore the folders. There is a script in the docs folder for this. https://github.com/qutip/qutip.github.io/blob/master/docs/remove_leading_underscores.py

HTML File Updates¶

• Edit download.html

  • The ‘Latest release’ version and date should be updated.

  • The tar.gz and zip links need to have their micro release numbers updated in their filenames, labels and trackEvent javascript. These links should point to the “Source code” links that appeared when you made in the GitHub Releases section. They should look something like https://github.com/qutip/qutip/archive/refs/tags/v4.6.0.tar.gz.

  • For a minor or major release links to the last micro release of the previous version will need to be moved (copied) to the ‘Previous releases’ section.

• Edit _includes/sidebar.html

  • The ‘Latest release’ version should be updated. The gztar and zip file links will need the micro release number updating in the traceEvent and file name.

  • The link to the documentation folder and PDF file (if created) should be updated.

• Edit documentation.html

  • The previous release tags should be moved (copied) to the ‘Previous releases’ section.