# 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)