Release Guide
Introduction
This document describes the procedure for making a release of PlasmaPy. Developers should revise and expand these instructions while performing each release, and may refer to Astropy’s release procedures for guidance.
Throughout this guide, 0.9.0
denotes the version you’re releasing.
Tip
Split up pre-release tasks into multiple focused pull requests to facilitate quicker code reviews.
Announce the release timeline
Create an issue on GitHub for the release with a checklist of tasks to be performed roughly one month before.
About three weeks before a minor or major release, announce that a feature freeze will occur one week before the anticipated release date. Only pull requests with a limited scope that do not significantly change functionality should be merged during the feature freeze.
Begin a code freeze about three weekdays before a release. Only bugfixes and pull requests that are directly related to the release should be merged during the code freeze.
Update metadata
Begin an upload to Zenodo for the new release using the
team@plasmapy.org
login, and reserve a DOI.Open a pull request to update and alphabetize the author list in
docs/about/credits.rst
,.mailmap
, andCITATION.cff
, the latter using the Citation File Format. Missing ORCID identifiers may be added.
Perform code quality checks
Create a pull request to revise changelog entries to make sure that they are understandable, necessary, and in the correct category.
Tip
Apply the No changelog entry needed label to pull requests that change multiple changelog entries in order to skip the changelog entry check.
Open a pull request to re-execute pre-executed notebooks, such as those for charged particle radiography.
Run
make linkcheck
indocs/
, and if necessary, open a pull request to update redirects and fix broken links. The reserved DOI link indocs/about/citation.rst
will not work yet since the Zenodo record will not be published until after the official release.Tip
Use
linkcheck_allowed_redirects
indocs/conf.py
to specify allowed redirects. For example, DOI links are always redirects, but are significantly more persistent than hyperlinks.Make sure that all tests are passing.
Go to the Actions page.
Click on the CI tab → Run workflow.
Click on the weekly tests tab → Run workflow.
Enjoy life for 15 minutes.
Fix any failures, and then repeat these steps.
Create the release branch
Go to the Release action, hit the Run workflow button, fill in the required values and hit Run Workflow. Refresh the page and make sure the new job goes through. Fix whatever made it fail.
For major and minor releases, activate the new branch’s version on on Read the Docs.
Publish the release
Go to the GitHub page to draft a new release. We will perform a pre-release first.
Set the Target to
v0.9.x
.For Choose a tag, put
0.9.0rc1
.Under title, put
v0.9.0rc1
.Mark this as a pre-release.
Click on Publish release.
The release is handled via
.github/workflows/python-publish.yml
.In a few minutes, check PlasmaPy releases on PyPI to make sure that version
0.9.0rc1
has been released and is marked as pre-release.Tip
If the release did not work, it may be necessary to create a new API token for PyPI and update the secret on GitHub.
Test that the new release is working. In a new virtual or conda environment, run
pip install plasmapy==0.9.0rc1
to make sure that the new version installs correctly.
Open Python and run
import plasmapy
anddir(plasmapy)
.Run
plasma-calculator
from the terminal to make sure that the plasma calculator is behaving correctly.
Fix any errors that arise, and re-run the CI and weekly tests checks.
Go to the GitHub page to draft a new release. We will now perform the
0.9.0
release.Set the Target to
v0.9.x
.For Choose a tag, put
0.9.0
.Under title, put
v0.9.0
.Copy the release notes from the changelog, using the beginning of
docs/whatsnew/0.9.0.rst
Click on Publish release.
In a few minutes, check PlasmaPy releases on PyPI to make sure that the
0.9.0
release is present. If it is, congratulations!Tip
To get the number of PRs merged and issues closed since the last release for the release notes, perform GitHub searches like
is:pr merged:>=2021-11-19
andis:issue closed:>=2021-11-19
, using the date one day after the last release.Merge the pull request from the
v0.9.x
branch tomain
.In the
v0.9.x
branch, change the line inbinder/requirements.txt
that has.
toplasmapy == 0.9
.Open one of the binder examples in the docs for
v0.9.x
, and run the following commands to verify that the released version of PlasmaPy begins with0.9
.import plasmapy print(plasmapy.__version__)
Merge the
v0.9.x
branch into thestable
branch on GitHub:git checkout v0.9.x git pull git checkout stable git merge v0.9.x git push
Post-release
Make the release on conda-forge. The helpful conda-forge bots should automatically open up a PR on conda-forge/plasmapy-feedstock. If nothing breaks, it’ll even get auto-merged.
If tests fail, look at the
recipe.yaml
file — usually it’s either changed dependencies or the simple import tests there.
Upload the release to the Zenodo record corresponding to the reserved DOI, making the metadata consistent with
CITATION.cff
.
Advertise the release
Write a post on the release on PlasmaPy’s website.
Notify plasma physics communities about the release on:
PlasmaPy newsletter
APS DPP Engage forum (requires login)
Discuss how the release procedure went during the next community meeting.
Update the release guide to reflect any changes.