DEV: Release guide

Since I'm the only member of the JDAT team who has done a specreduce release on GitHub, I was asked to outline the steps I usually take. Please feel free to adapt them as needed or to turn this page into a section of the developer documentation on ReadTheDocs.

1. Merge outstanding pull requests.
2. Are any relevant merged pull requests missing from the changelog? If so, add them.
   • It can be helpful to Ctrl+f/Cmd+f "#" on the commits page to find the pull requests that have been merged since the last release.
3. Open a pull request with a modified changelog.
   • Add an empty section for the release that will follow this one. Be sure to move "(unreleased)" from the current release's header to the header of the empty section.
   • Merge (along with any changes from #2) once ready.
4. Fetch main, including tags. [e.g., git fetch upstream main --tags]
5. Rebase main. [e.g., git rebase upstream/main main]
6. Create a tag. For version 43.7.3, the tag and message would have the following format: git tag -s v43.7.3 -m "Release v43.7.3"
   • You need to have SSH set up locally in order to create a tag. Steps from here (including the amendments in the notes for steps 2 and 3) and here were helpful for me; swap sections as needed depending on your system.
7. Push the new tag upstream. [e.g,. git push upstream --tags]
8. Find the tag on GitHub.
   • Pushing the tag to main is what actually sets off the release to PyPI – check the repository's "Actions" tab to see that it triggers the related workflow. You still need to complete the release on the GitHub side, however.
9. Start the release on GitHub.
   • Move over to the Releases page and click "Draft a new release".
   • In "Choose a tag", click your new tag's name.
   • The release's title should be the same as the tag's name (e.g., "v43.7.3").
   • The release notes are usually copied from the corresponding section of CHANGES.rst. (Adapt the section headers for use with Markdown by adding "##" before them and removing RST section title styling beneath them.)
   • You can also autogenerate a "What's changed" section below the changelog text by clicking the "Generate release notes" button above the box for release text. It's helpful to separate it from the copied changelog content by putting a dividing line between them (e.g., "---").