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.
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
common_links.rstmay 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.
When removing or moving an object, reST 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
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
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