Release & Changelog Process
Relevant source files
The following files were used as context for generating this wiki page:
The Release & Changelog Process in infrahub-sync uses an automated system to manage versioning and documentation. Contributors provide news fragments for every change, which the system assembles into a formal changelog during the release cycle. This process ensures that release notes reflect actual technical changes rather than generic pull request titles.
Sources: RELEASING.md:5-15, AGENTS.md:104-106
Automated Release Workflow
The project implements a standard release flow where no release artifacts are edited by hand. The process begins by dispatching a specific GitHub Action to prepare a release pull request. Merging this pull request triggers the final tagging and publication to PyPI.
Sources: RELEASING.md:17-20, changelog/+towncrier-release-process.housekeeping.md:1-5
Release Preparation Phases
- Labeling: Maintainers apply specific labels to pull requests. These labels determine if the next version is a Major, Minor, or Patch bump.
- Dispatching: A user triggers the
trigger-push-stable.ymlworkflow from the GitHub Actions tab. - Assembly: The workflow resolves the version number, updates
pyproject.toml, and usestowncrierto assembleCHANGELOG.mdfrom fragments. - Review: The system opens a
chore(release): {VERSION}pull request for human review.
Sources: RELEASING.md:28-66, dev/constitution.md:162-167
The following diagram illustrates the automated sequence from merging code to publishing a package:
Sources: RELEASING.md:52-85
Changelog Management with Towncrier
The project uses towncrier to manage release notes. Contributors must add a news fragment under the changelog/ directory for every pull request merged into main. The changelog-check.yml workflow fails a PR if this fragment is missing, unless the ci/skip-changelog label is applied.
Sources: AGENTS.md:104-110, CHANGELOG.md:1-4
News Fragment Types
Fragments are named using the format <id>.<type>.md. The allowed types are defined in pyproject.toml.
| Type | Description |
|---|---|
security | Security-related changes or fixes |
removed | Removed features or code |
deprecated | Deprecated features slated for removal |
added | New features or capabilities |
changed | Changes to existing functionality |
fixed | Bug fixes |
housekeeping | Maintenance, CI, or documentation updates |
Sources: pyproject.toml:343-379, RELEASING.md:110-114
Creating a Fragment
You can create a fragment manually or via the CLI:
uv run --extra dev towncrier create -c "Short description of what changed." 123.fixed.md
Sources: AGENTS.md:108-112
Versioning Logic
The version bump is calculated automatically based on labels attached to the pull requests merged since the last release.
| Label | Version Bump | Example |
|---|---|---|
changes/major, type/breaking-change | Major | 1.0.0 → 2.0.0 |
changes/minor, type/feature, type/refactoring | Minor | 1.0.0 → 1.1.0 |
changes/patch, type/bug, type/housekeeping | Patch | 1.0.0 → 1.0.1 |
Sources: [RELEASING.md:30-40]
Manual Release Procedures
While automated releases are recommended, two escape hatches exist for emergency or custom scenarios.
Manual GitHub Release
This method involves manually updating the version in pyproject.toml, running uv lock, and creating a release via the GitHub UI. This bypasses the automated changelog assembly; fragments remain unconsumed and CHANGELOG.md is not updated.
Sources: RELEASING.md:87-101
Manual Workflow Dispatch
Users can trigger workflow-publish.yml directly to build and upload the package to PyPI. This requires pyproject.toml to already contain the desired version string.
Sources: RELEASING.md:103-108
Workflow Files Reference
| Workflow | Trigger | Purpose |
|---|---|---|
changelog-check.yml | PR to main | Ensures a news fragment exists |
trigger-push-stable.yml | Manual | Bumps version, assembles changelog, opens Release PR |
release-publish.yml | Push to main | Tags the commit and creates GitHub Release |
trigger-release.yml | Release Published | Starts the PyPI upload process |
workflow-publish.yml | Reusable | Builds wheels and uploads to PyPI |
Sources: RELEASING.md:144-150
Summary
The Release & Changelog Process prioritizes automation and contributor-driven documentation. By requiring news fragments and using towncrier for assembly, the project maintains a high-quality CHANGELOG.md without manual editing. Maintainers control the release cadence by dispatching specific preparation workflows, while GitHub Actions handle the mechanical tasks of version bumping, tagging, and PyPI distribution.