Changelog Guide

A changelog tells users and contributors what notable changes have been made between each release. Pull requests to PlasmaPy need changelog entries before they can be merged, except when the changes are very minor. PlasmaPy uses towncrier to convert the changelog entries into the full changelog. An example changelog entry would be:

Added a page in the contributor guide that describes how to add
changelog entries.

Adding a changelog entry

Please follow these steps to add a changelog entry after submitting a pull request to PlasmaPy’s main branch.

  1. In the changelog directory, create a new file entitled ⟨number⟩.⟨type⟩.rst, where ⟨number⟩ is replaced with the pull request number and ⟨type⟩ is replaced with one of the following changelog types:

    • breaking: For backwards incompatible changes that would require users to change code. Not to be used for removal of deprecated features.

    • bugfix: For changes that fix bugs or problems with the code.

    • doc: For changes to the documentation.

    • feature: For new user-facing features and any new behavior.

    • removal: For feature deprecation and/or removal.

    • trivial: For changes that have no user-facing effects.

    Pull request #1198 includes an update to the documentation, so the file should be named 1198.doc.rst. If you are unsure of which changelog type to use, please feel free to ask in your pull request.

    Tip

    When a pull request includes multiple changes, use a separate changelog file for each distinct change.

    If the changes are in multiple categories, include a separate changelog file for each category. For example, pull request #1208 included both a breaking change and a new feature, and thus needed both 1208.breaking.rst and 1208.feature.rst.

    For multiple changes in a single category, use filenames like 1208.trivial.1.rst and 1208.trivial.2.rst.

  2. Open that file and write a short description of the changes that were made. As an example, 1198.doc.rst might include:

    Added a page in the contributor guide that describes how to add
    changelog entries.
    
  3. Commit the file and push the change to branch associated with the pull request on GitHub.

Changelog guidelines

  • Changelog entries will be read by users and developers of PlasmaPy and packages that depend on it, so please write each entry to be understandable to someone with limited familiarity of the package.

  • Changelog entries are not required for changes that are sufficiently minor, such as typo fixes. When this is the case, a package maintainer will add the No changelog entry needed label to the pull request.

  • Use the past tense to describe the change, and the present tense to describe how the functionality currently works.

  • A changelog entry may include multiple sentences to describe important context and consequences of the change. Because towncrier automatically reflows text, keep entries to a single paragraph.

  • Use intersphinx links to refer to objects within PlasmaPy, and include the full namespace. For example, use `~plasmapy.particles.particle_class.Particle` to refer to Particle. The tilde is included to hide all but the name of the object.

  • Show the full former namespace for objects that have been removed or moved, and use double back ticks so that the name is rendered as code without attempting to create a link.

    Removed the ``plasmapy.physics`` subpackage. The functionality from
    that subpackage is now in `plasmapy.formulary`.
    
  • Substitutions as defined in common_links.rst may be used in changelog entries.

  • The pull request number does not need to be included inside the changelog entry because it will be added automatically when the individual entries are converted into the full changelog.

  • If a change is supplanted by another change during the release cycle, keep the files for both changelog entries. When the change is significant, mention in the earlier entry that the change was superseded or reverted and include a link to the appropriate pull request.

Building the changelog

During the release cycle, towncrier is used to build the changelog. To install towncrier and the other packages needed to develop PlasmaPy, go to the top-level directory of your local clone of PlasmaPy and run:

pip install -r requirements.txt

Configuration files for towncrier are in pyproject.toml.

To run towncrier, enter the top-level directory of PlasmaPy’s repository. To print out a preview of the changelog, run:

towncrier --draft

To convert the changelog entries into a changelog prior to the 0.7.0 release, run:

towncrier --version v0.7.0

This will create CHANGELOG.rst in the top-level directory, with the option to delete the individual changelog entry files. The full steps to update the changelog are described in the Release Guide.

Tip

Towncrier can be used to create a new changelog entry and open it for editing using a command like:

towncrier create --edit ⟨number⟩.⟨type⟩.rst

Here, ⟨number⟩ is replaced with the pull request number and ⟨type⟩ is replaced with the one of the changelog types as described above.