Towncrier Workflow For Pull Requests

This repository uses Towncrier to build the release changelog from small news fragments. Most pull requests should include exactly one fragment.

Goal

The goal is to describe user-visible changes in a small, reviewable fragment that can later be collected into CHANGELOG.md.

When A Fragment Is Required

Add a fragment for:

  • new features,

  • behavior changes,

  • bug fixes,

  • deprecations or removals,

  • and other user-facing changes.

You can usually skip a fragment for:

  • tiny documentation-only fixes such as typos,

  • or purely internal changes that do not affect users, if the maintainers agree.

If you are unsure, add a fragment.

Create The Fragment File

Create a file under newsfragments/ named:

<ID>.<type>.md

Where:

  • <ID> is the issue number when known, otherwise use a temporary placeholder and rename it before merge,

  • and <type> matches one of the configured fragment types.

Common examples are:

  • feature

  • bugfix

  • doc

  • removal

  • misc

Example filenames:

newsfragments/123.feature.md
newsfragments/124.bugfix.md
newsfragments/125.doc.md

Write The Fragment Content

Keep the fragment to one short, user-facing sentence. Do not add headings or multiple paragraphs. Describe the observable change rather than the internal implementation.

Good examples:

  • Added NACA 4-digit airfoil generation through the public factory API.

  • Fixed handling of zero angle-of-attack inputs in the panel solver.

Less useful examples:

  • Refactored helper functions in foo.py.

Check The Fragment Locally

Verify that your branch contains a valid fragment with:

uv run towncrier check

This should succeed before the pull request is opened or merged.

Common Mistakes

  • putting the fragment in the wrong directory,

  • using an unknown fragment type,

  • writing an overly detailed or multi-paragraph fragment,

  • or describing internal refactors instead of user-visible behavior.