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.”

  • “Documented Buffalo Core compatibility expectations for downstream projects.”

Less good:

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

Downstream Impact

Buffalo Core sits below other Buffalo projects, so release notes should make downstream impact explicit when it exists. If a change affects import paths, public typing aliases, diagnostics behavior, or normalization helpers, say that directly in the fragment.

For example, prefer:

  • “Documented that FloatInput is part of the stable shared typing surface used by Buffalo Wings and Buffalo Panel.”

Instead of:

  • “Improved typing docs.”

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)