Maintaining Sphinx Gallery

This document contains tips for maintenance.

How to make a release

1. Update CHANGES.rst and version in a PR

1. 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. The changelog can generated with the following:

   github_changelog_generator --since-tag=v<version> --token <your-40-digit-token>
   

   To avoid the need to pass --token, you can use export CHANGELOG_GITHUB_TOKEN=<your-40-digit-token> instead.

2. Update PR labels on GitHub if necessary and regenerate CHANGELOG.md so that PRs are categorized correctly. The labels we currently use are:

   bug

   For fixed bugs.

   enhancement

   For enhancements.

   api

   For API changes (deprecations and removals).

   maintenance

   For general project maintenance (e.g., CIs).

   documentation

   For documentation improvements.

   Once all PRs land in one of these categories using the changelog generator, manually edit CHANGELOG.md to look reasonable if necessary.

3. Propagate the relevant changes to CHANGES.rst. You can easily convert it reST with pandoc:

   pandoc CHANGELOG.md --wrap=none -o CHANGELOG.rst
   

   Then copy just the sections to CHANGES.rst. Keep ``CHANGELOG.md`` for later.

4. Update the version in sphinx_gallery/__init__.py, which should end in .dev0. You should replace .dev0 with 0 to obtain a semantic version (e.g., 0.12.dev0 to 0.12.0).

5. Open a PR with the above changelog and version changes (along with any updates to this maintainers.rst document!).

6. Make sure CIs are green.

7. Check that the built documentation looks correct.

8. Get somebody else to make sure all looks well, and merge this pull request.

2. Finalize the release

1. Make sure CIs are green following the “Release” PR.

2. 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 with v. 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) and include a “Full changelog” link at the top, e.g.; [Full Changelog](https://github.com/sphinx-gallery/sphinx-gallery/compare/v0.13.0...v0.14.0)

   • Click Publish release when you are done.

   • Confirm that the new version of Sphinx Gallery is posted to PyPI.

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

4. Celebrate! You’ve just released a new version of Sphinx Gallery!

3. Post-release tasks

1. Check for any deprecations (e.g., git grep eprecat) and complete them, usually by removing code or some behavior in a PR.

2. Check and update minimum supported (old) Python and Sphinx versions (older than 2 years) plus check for any new ones, and update if necessary in a PR:

   • pyproject.toml (old)

   • .github/workflows/tests.yml (old and new)

   • README.rst::Installation (old)