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
changelogdirectory, create a new file entitled
⟨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.
docchangelog entry is not necessary if there is a corresponding
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
For multiple changes in a single category, use filenames like
Open that file and write a short description of the changes that were made. As an example,
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 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
docs/_global_substitutions.pymay 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 .[dev]
Configuration files for towncrier are in
To run towncrier, enter the top-level directory of PlasmaPy’s repository. To print out a preview of the changelog, run:
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.
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
⟨number⟩ is replaced with the pull request number and
⟨type⟩ is replaced with the one of the changelog types as