Maintaining Sphinx Gallery¶
This document contains tips for maintenance.
How to make a release¶
Check credentials and prerequisites¶
Sphinx Gallery is hosted on the pypi repository. To create a new release of Sphinx Gallery, you need to do these things: You should double-check a few things to make sure that you can create a new release for Sphinx Gallery.
Ensure that you registered an account on the PyPI index.
Ensure you have push access to the Sphinx Gallery pypi repository. Ask one of the Sphinx Gallery core developers if you do not.
Install the GitHub Changelog Generator. This is a small tool written in Ruby to generate a markdown list of recent changes.
Install the twine package. This is a package that helps you bundle and push new Python package distributions to pip.
Prepare for release¶
Update
CHANGES.rst
Use github_changelog_generator to gather all merged pull requests and closed issues during the development cycle. You will likely need to generate a Github token as Github only allows 50 unauthenticated requests per hour. In the command below
<version>
is the current (not development) version of the package, e.g.,0.6.0
. We do this because our failing discipline of writing in the CHANGES.rst all relevant changes, this helps our memory. It is a good idea to add appropriate labels (e.g., ‘BUG’) to issues and pull requests so they are categorized correctly in the CHANGES.rst generated.github_changelog_generator -u sphinx-gallery -p sphinx-gallery --since-tag=v<version> --token <your-40-digit-token>
Edit CHANGELOG.md to look reasonable (it will be used later). It’s a good idea to add labels to issues and pull requests so github_changelog_generator can correctly categorize them in in the CHANGES.rst file generated.
Propagate the relevant changes to CHANGES.rst. You can easily convert it RST with pandoc:
pandoc CHANGELOG.md --wrap=none -o CHANGELOG.rst
Build the docs cleanly
Make sure to clean all and have a clean build. Double-check visually that everything looks right.
Double check CIs
Make sure CIs are green on the master branch.
Update version
Update the version in
sphinx_gallery/__init__.py
, which should end in.dev0
. You should remove.dev0
, and the numbers that remain will become the version for this release.Open a Pull Request that contains the two changes we’ve made above
The version bump and the CHANGELOG update should be in the PR. Get somebody else to make sure all looks well, and merge this pull request.
Finalize the release¶
Create the new release on PyPI
Build a source distribution:
python setup.py sdist
Check the release:
twine check dist/sphinx-gallery-<version>.tar.gz
<version>
should be the release version, e.g.,0.7.0
.Upload to PyPI:
twine upload dist/sphinx-gallery-<version>.tar.gz
Again,
<version>
should be the release version, e.g.,0.7.0
.Confirm that the new version of Sphinx Gallery is posted to pypi.
Create a new release on GitHub
Go to the Draft a new release page.
The tag version is whatever the version is in
__init__.py
prepended withv
. E.g.,v0.7.0
.The release title is
Release <tag-version>
.The description should contain the markdown changelog you generated above (in the
CHANGELOG.md
file).Click Publish release when you are done.
Now that the releases are complete, we need to switch the “master” branch back into a developer mode. Bump the Sphinx Gallery version number to the next minor (or major) release and append
.dev0
to the end, and make a PR for this change.Celebrate! You’ve just released a new version of Sphinx Gallery!