SuperAPI AI Directory

creating-changelog-entries

Coding & development

View repository

Updated 10-16 03:11

About this skill

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

Quick Reference

uv run towncrier create -c "content of changelog entry" ${ISSUE}.${TYPE}.md

These commands use uv run, which runs the project's pinned Towncrier and is the convention across these Python projects. If your project doesn't use uv, drop the prefix (towncrier create ...) or use its runner (e.g. poetry run towncrier ...).

  • ISSUE — issue ID, or + when no issue exists (e.g. +pnpm-workspaces).
  • TYPE — one of the change types below.
Type Use For
added New features
changed Changes in existing functionality
deprecated Soon-to-be removed features
removed Now removed features
fixed Bug fixes
security Security vulnerabilities
housekeeping Internal maintenance and tooling (build, CI, dev scripts)

The available types come from the project's Towncrier config ([tool.towncrier]); the set above is the common default. How a project classifies some changes is project-specific — dependency-version bumps in particular land under changed in some projects and housekeeping in others, so follow the project's changelog guide rather than assuming.

Fragment Location

Fragments live in the directory Towncrier is configured to use (its directory setting — commonly the repo-root changelog/ or newsfragments/). towncrier create puts them there automatically — don't move them or hand-place them.

In a monorepo, they do not belong in a sub-package directory such as backend/changelog/ or frontend/changelog/. A fragment found there was hand-written in the wrong place and must move to the configured directory.

Exception: a nested package with its own Towncrier config (e.g. a submodule like Infrahub's python_sdk) keeps its own fragments in that package's configured directory — those stay put and must not be moved to the root.

Writing Good Messages

  • Write from the user's perspective.
  • Focus on what changed, not how.
  • Use past tense ("Fixed", "Added", "Removed").
  • Keep it concise — one sentence.
  • Avoid technical jargon.

Examples

# Bug fix for issue #1234
uv run towncrier create -c "Fixed sidebar collapse issue" 1234.fixed.md

# New feature for issue #7549
uv run towncrier create -c "Added breadcrumb navigation for hierarchical schemas" 7549.added.md

# Housekeeping without an issue
uv run towncrier create -c "Migrated the frontend build to pnpm workspaces" +pnpm-workspaces.housekeeping.md

Common Mistakes

  • Hand-writing the fragment file. Use towncrier create so the name and location are correct.
  • Placing it in a sub-package directory (e.g. backend/changelog/) instead of the configured fragments directory.
  • Describing the implementation. "Refactored the auth-token cache layer" → instead say what the user sees: "Fixed users being unexpectedly logged out".
  • Wrong tense or multiple sentences. One past-tense sentence.

See Also

  • Towncrier documentation — fragment types, configuration, and CLI options.
  • Keep a Changelog — changelog best practices.
  • Your project's contributing or changelog guide for project-specific conventions (in Infrahub: docs/docs/development/changelog.mdx).