Towncrier Workflow for Pull Requests

This repository uses Towncrier to build the release changelog from small “news fragments”. Pull requests should include exactly one fragment. If the pull request is too large, then split it into smaller pieces that can be distilled down to a one fragment description.

When a Fragment is Required

Add a fragment for:

  • new features

  • behavior changes

  • bug fixes

  • deprecations/removals

  • anything user-facing

You can usually skip a fragment for:

  • tiny documentation-only changes (typos)

  • changes that do not affect users (pure refactors), if the maintainers agree

If unsure: add a fragment.

Adding a Fragment

Create a file under newsfragments/ named:

<ID>.<type>.md

Where:

  • <ID> is the issue number if you know it; otherwise use a placeholder like 000 and rename before merge.

  • <type> is one of:

    • feature — new user-facing capability (“Added …”)

    • bugfix — fix a user-visible defect (“Fixed …”)

    • doc — documentation changes (“Documented …”)

    • removal — removed/deprecated behavior (“Removed …”)

    • misc — small changes that don’t fit above but are still worth noting

Examples:

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

Content Rules

  • One short, user-facing sentence.

  • No Markdown headings.

  • Avoid internal implementation details; describe the user-visible change.

Good:

  • “Added NACA 4-digit airfoil generator with thickness and camber controls.”

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

Less good:

  • “Refactored function foo() to use helper bar()” (not user-facing)

Checking Locally

With Towncrier installed, you can verify that your branch has a fragment:

uv run towncrier check

This should succeed if you added a valid fragment file.

Common Mistakes

  • Putting the fragment in the wrong directory (must be in newsfragments/)

  • Using an unknown type (must match configured types)

  • Writing a multi-paragraph fragment (keep it short)