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 acccount 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. We do this because our failing discipline of writing in the CHANGES.rst all relevant changes, this helps our memory.
github_changelog_generator sphinx-gallery/sphinx-gallery --since-tag=v0.5.0 --token <your-40-digit-token>
Edit CHANGELOG.md to look reasonable (it will be used later)
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 remaining numbers 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-0.4.0.tar.gz
Upload to PyPI:
twine upload dist/sphinx-gallery-<version>.tar.gz
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.3.0
. - The release title is
Release << tag-version >>
. - The description should contain the markdown changelog
you generated above (in the
CHANGELOG.md
file). Make sure to update any links to point to the tag that will be created for this release (e.g., changeHEAD
tov0.3.0
). - 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!