Changelog & Towncrier
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub Backup uses Towncrier to manage its changelog and release notes. This system replaces manual editing of CHANGELOG.md with a workflow based on individual "news fragments." These fragments reside in the changelog/ directory and are combined into the main changelog at release time.
This approach ensures that every change carries its own entry and prevents merge conflicts in the CHANGELOG.md file during collaborative development. CI processes enforce the presence of these fragments for every pull request targeting the main branch.
Sources: AGENTS.md:43-47, changelog/+towncrier.housekeeping.md:1
News Fragments
A news fragment is a small Markdown file created alongside a code change. Each fragment captures a specific update, such as a bug fix, a new feature, or a security patch.
Fragment Types
The project categorizes changes into specific types, which Towncrier uses to organize the rendered changelog.
| Type | Directory | Description |
|---|---|---|
security | changelog/security | Security-related fixes or updates. |
removed | changelog/removed | Removed features or components. |
deprecated | changelog/deprecated | Features marked for future removal. |
added | changelog/added | New functionality or features. |
changed | changelog/changed | Modifications to existing functionality. |
fixed | changelog/fixed | Bug fixes. |
housekeeping | changelog/housekeeping | Internal, tooling, or maintenance work. |
Sources: AGENTS.md:48-49, pyproject.toml:57-84
Naming Convention
Fragments must follow a specific naming pattern to be recognized by the build system:
- Standard format:
<issue_number>.<type>.md(e.g.,42.fixed.md). - Slug format: If no issue or PR number exists, use a descriptive slug prefixed with
+(e.g.,+retention-dry-run.added.md).
Sources: AGENTS.md:48-49, pyproject.toml:55
Towncrier Workflow
The workflow involves creating fragments during development, previewing them in drafts, and consuming them during the release process.
The diagram shows the lifecycle of a changelog entry from developer creation to final release build.
Common Commands
You interact with Towncrier using the uv tool to execute commands defined in the project configuration.
- Create a fragment:
uv run towncrier create -c "Fixed the thing" 42.fixed.md - Preview a draft changelog:
uv run towncrier build --draft --version X.Y.Z - Build the final changelog:
uv run towncrier build --version X.Y.Z
Sources: AGENTS.md:48-52
Configuration and CI Enforcement
The Towncrier configuration is defined within the pyproject.toml file. This configuration specifies the location of fragments, the template used for rendering, and the format for issue links and titles.
- Directory: Fragments are stored in
changelog/. - Template: The project uses
changelog/towncrier.md.template. - Issue Format: Issues are linked as
[#issue](https://github.com/opsmill/infrahub-backup/issues/issue). - Version Management: Releases are versioned from git tags. Versions must be passed explicitly to Towncrier because the
pyproject.tomlversion only describes the e2e test suite, not the Go binaries.
CI enforces the Changelog / News fragment present check on pull requests targeting main. Changes that require no entry can opt out by applying the ci/skip-changelog label.
Sources: AGENTS.md:45-53, pyproject.toml:47-56
Summary
The News Fragment system provides a structured and automated way to maintain a detailed history of the Infrahub Backup project. By requiring fragments for every PR, the project ensures that documentation keeps pace with code changes, providing transparency for users and maintainers regarding new features, fixes, and internal improvements.
Sources: AGENTS.md:43-47, specs/004-backup-retention-policy/tasks.md:92