Release Notes Workflow

Buffalo Core release notes should help downstream Buffalo projects understand what changed and whether they need to act. Because Buffalo Core sits below other projects, seemingly small public changes can have broad effects.

Goals

Release notes should make the following easy to answer:

  • What changed for public users of Buffalo Core?

  • Does Buffalo Wings, Buffalo Panel, or another downstream project need to update code or docs?

  • Is the change additive, corrective, or compatibility-affecting?

News Fragment Expectations

Use Towncrier fragments for all user-visible changes. Follow the Towncrier workflow for the mechanics of adding fragments.

When a change affects the public API or downstream integration, the fragment should say so directly.

Good examples:

  • “Added buffalo_core.typing.IntInput to support shared integer-input normalization across Buffalo projects.”

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

  • “Changed diagnostic field documentation so Sphinx renders dataclass attributes correctly.”

Better when downstream projects are affected:

  • “Moved Buffalo Wings shared numeric facades onto Buffalo Core and documented the new dependency direction.”

  • “Documented that changes to OperationResult are compatibility-sensitive for Buffalo Panel and Buffalo Wings.”

Release Summary Expectations

When preparing a release, review the pending fragments and make sure the resulting changelog answers these questions:

  1. Which changes are likely to matter to downstream project maintainers?

  2. Are there any import-path, typing, or behavior changes that need follow-up work in Buffalo Wings or Buffalo Panel?

  3. Does the release contain any compatibility-sensitive changes that should be highlighted separately?

If the answer to any of those is yes, add a short maintainer note to the release description or release announcement. The changelog entry should not force downstream maintainers to infer that impact for themselves.