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.

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.

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.
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.
```
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 :guilabel`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.

Tip

When removing or moving an object, reStructuredText links that follow the original namespace will break, causing the documentation build to fail.

Text in single back ticks is used to link to code objects, while text in double back ticks is treated as an inline literal. To remedy this problem in old changelog entries, change the broken link into an inline literal by surrounding it with double back ticks instead. Remove the tilde if present. For example, `~plasmapy.subpackage.module.function` should be changed to:

``plasmapy.subpackage.module.function``

Outside of the changelog, the namespace should be corrected rather than changed into an inline literal.

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 .[dev]

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.