Releasing a new version of pims

Note: These are draft instructions that will be updated as we release v0.5.

Releasing a new version of pims can be as simple as using the twine tool to put the distribution on PyPI, and letting conda-forge build conda packages.

In addition to needing push access to the soft-matter/pims repository, to complete the PyPI and conda-forge steps you (or someone you're working with closely) will need write access to the PyPI page and the conda-forge/pims-feedstock repository. Other maintainers of pims can grant those privileges.

Checklist

1. Make sure all issues tagged with the release's milestone are closed or moved to a future milestone.

2. Make sure dependencies listed in setup.py are up to date, including their minimum versions. Make sure that all packages (i.e. subdirectories with required code) within pims are listed here.

3. Tag a release candidate like git tag v0.0.0rc1.

4. Push the tags to the soft-matter/pims repo.

   git push upstream --tags

5. Install pypandoc, which renders the README.

6. Reinstall pims locally to ensure that the version number is updated by versioneer.

   python setup.py develop

7. Build the source distribution packages

   python setup.py sdist

8. Install twine to register and upload the source distribution to PyPI. You need to be a maintainer or owner of pims on PyPI; you can ask an existing owner to add you.

9. Register and upload the source distribution, compressed as zip and as tarball.

   twine upload dist/<name of package>.tar.gz

10. For the actual release: Wait for the regro-autotick-bot to file a PR at conda forge to update the conda recipe (it may take an hour or more). Make sure the versions agree with setup.py. While you're waiting, prepare your changes to the docs repository and draft a GitHub release (see below).

11. For a release candidate: the bot will not create a PR. It's still a good idea to manually create a test PR at conda forge; this will cause the automated CI tests to check that the conda package will build smoothly. Don't merge your release candidate PR!

    • Go to the PyPI release page and get the SHA256 hash of this release from the downloads page.
    • Create a pull request from your fork of the conda forge feedstock, updating recipe/meta.yaml with information from the PyPI release. (You can use the fork soft-matter/pims-feedstock instead of your own fork, but then you will not get to try out the conda-forge's re-render bot.)
    • As you are creating the PR, follow the helpful checklist in the default PR message!

12. If all checks (including all automated tests on pims-feedstock) are positive, repeat, tagging an actual release and merging the pims-feedstock PR.

13. Check the version of the dev docs here. If the content is up to date, but the new version you tagged is not listed at the top of the page, you need to restart the latest Travis build on the master branch.

    • Go to the list of branches on Travis
    • Click on the build (e.g. "#1234 passed")
    • If you see "Restart build", click that. Otherwise, under the "More options" menu, choose "Trigger build" and supply a brief description (e.g. "Rebuild docs for v0.5 release").
    • Check the dev docs again. Even after the build is done, you may have to wait a minute for the change to propagate to the GitHub Pages web servers.

14. Manually make some changes to the docs repository:

    • force-pull the docs repository (git fetch --all, git reset --hard upstream/master)
    • copy over the pims/dev docs to a new version folder (e.g. cp -r pims/dev pims/v0.5)
    • edit the redirect in pims/stable/index.html to point to the new version
    • edit robots.txt to keep old versions of the docs from appearing in search results
    • push the docs repository

15. From soft-matter/pims repository's Releases page, draft and publish the release on GitHub. (To make it extra nice, you can use pandoc to convert the new release notes to Markdown: pandoc -f rst -t markdown.)