Changelog Guide

Introduction

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. Some example changelog entries are:

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

The ``oldname`` argument to `plasmapy.subpackage.module.function` has
been deprecated and will be removed in a future release. Use
``newname`` instead.

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.

    • internal: For refactoring of the internal mechanics of the code and tests in ways that do not change the application user interface.

    • removal: For feature deprecation and planned removals.

    • trivial: For minor changes that do not change the application programming interface.

    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.

    Note

    A doc changelog entry is not necessary if there is a corresponding feature changelog entry.

    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 or fixed hyperlinks. 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 docs/_global_substitutions.py 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.

  • When a changelog entry describes changes to functionality, it is not necessary to mention the corresponding changes to the tests.

  • 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 -e .[docs]

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 v2024.5.0 release, run:

towncrier build --version=v2024.5.0

This command will ask for permission to delete changelog entries, and then create CHANGELOG.rst in the top-level directory.

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

Replace ⟨number⟩ with the pull request number and ⟨type⟩ with the one of the changelog types as described above.