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, and CITATION.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 in docs/, and if necessary, open a pull request to update redirects and fix broken links. The reserved DOI link in docs/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 in docs/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 fortnightly 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 and dir(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 fortnightly 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 and is:issue closed:>=2021-11-19, using the date one day after the last release.

  • Merge the pull request from the v0.9.x branch to main.

  • In the v0.9.x branch, change the line in binder/requirements.txt that has . to plasmapy == 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 with 0.9.

      import plasmapy
print(plasmapy.__version__)

  • Merge the v0.9.x branch into the stable 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.