This issue contains the procedure for releasing a new version of PlasmaPy.

Planning the release

• Create an issue for the release.
• Update milestones for issues & pull requests (PRs). 🛣️

Code quality updates

• Revise changelog entries to make sure that they are understandable, necessary, and correctly categorized. Add the no changelog entry needed label to skip doing changelog checks. 📜
• Run the GitHub Action for checking hyperlinks 🔗, and update broken links. Use linkcheck_allowed_redirects in docs/conf.py to allow redirects (e.g., from doi.org). Update or delete the alias field for authors in CITATION.cff who have changed their GitHub username.
• Run git log --format="%aN <%aE>" | sort -u, and update .mailmap if there are any duplicate contributors in the output. 📧
• Update pinned requirements. 📍
• Run pre-commit autoupdate followed by pre-commit run --all-files. Fix any new errors and commit the changes.

Make sure that all tests are passing on main

• Run the tests.
• Run the weekly tests.
• ✅ Fix any failures and repeat.

Perform the release

• Begin an upload to Zenodo for a new version of this record, using the [email protected] login. Reserve a DOI. 🏷️
• Run the GitHub Action to mint a release 🍬, specifying the version (i.e., 2024.10.0 or 2024.10.0rc1 for a release candidate) and copying the reserved DOI from Zenodo. This workflow will update metadata, build the changelog, create the release branch (i.e., 2024.10.x), and tag the release.
• Create a release on GitHub. 🚀
  • Choose the newly created tag (e.g., v2024.10.0), and use it as the title. (The release will be performed from the tag, so it is not necessary to select the branch.) 🏷️
  • Select the option to automatically generate release notes. 📜
  • Select the option to create a discussion for the release under the General category.
  • For official releases, make sure the checkbox is selected for Set as the latest release. For beta releases or release candidates (e.g., v2024.10.0rc1), specify it as a pre-release.
  • Click on Publish release, which will create the GitHub release and trigger the GitHub workflow to publish to PyPI. 🚀
  • Check the release history on PyPI to make sure that the release was successful. 🆕
• Create a pull request to merge the v2024.10.x branch back into main.
• Merge but do not squash this PR back into main, and do not delete the v2024.10.x branch.

Following the release

• Download a .tar.gz file of the tagged release from the list of tagged versions on GitHub, and upload it to Zenodo.
  • Update the author list with new authors from the automatically generated release notes or CITATION.cff.
  • Update the bibliography, and publish the release to Zenodo.
• Fix any problems with the automated pull request to conda-forge feedstock, if necessary. This step should be automatic, but may take a while.
• Update requirements in the conda-forge feedstock in recipe/meta.yaml, in particular when there is a new version of Python.

Update documentation

• Delete the stable branch on GitHub, if it exists.
• Activate the current and prior release on the versions page on RTD, if necessary. If the documentation fails to build for a release, activate the corresponding branch (e.g., activate the v2023.10.x branch instead of the v2023.10.0 tag).
• Check that the documentation builds correctly for the release branch. If the documentation build fails, create a new stable branch from the release branch (e.g., 2024.10.x) and fix any problems with the documentation build. The stable branch is needed if the documentation build for the release fails or if we make any changes to the documentation between releases. The stable documentation build will point to the stable branch on GitHub if it exists. Otherwise, it will point to the most recent release on GitHub. 📚
• Verify that the citation page is up-to-date and the DOI link points to the most recent release.

Test the release

• After activating a new virtual or conda environment, make sure that the released version installs correctly with pip install --upgrade plasmapy.
• Open Python and run import plasmapy, dir(plasmapy), and plasmapy.__version__.
• Run plasma-calculator from the command line.
• Verify that the new version can be installed with conda.

After the release

• Announce the release at the community meeting.
• Update the release checklist, as needed.
• Create an issue for the release to occur ∼3–4 months after this one.
• Close this issue.