creating-changelog-entries
Creating Changelog Entries
Overview
Towncrier assembles the changelog from per-change "fragment" files — one small file per change, collected and rendered at release time. This skill applies to any project that uses Towncrier. Every issue fix or new feature should ship with a fragment, written short and user-facing: describe what changed, not how it was implemented.
Core rule: always create fragments with towncrier create, never hand-write them. The command derives the location and naming from the Towncrier config and places the fragment correctly from anywhere in the repo.
When to Use
- You fixed a bug or added a feature and are about to commit or open a PR.
- You're asked to "add a changelog entry", "create a news fragment", or "run towncrier".
- A PR checklist or CI flags a missing changelog entry.
When NOT to use: the project doesn't use Towncrier; pure internal refactors with no user-facing or maintenance impact; and changes the team has explicitly decided don't warrant an entry. (Most internal maintenance still gets a housekeeping fragment.)