Release Process & Changelog

Relevant source files

The following files were used as context for generating this wiki page:

• dev/guides/releasing-the-collection.md
• changelog/+towncrier-release-process.housekeeping.md
• specs/002-towncrier-release-process/spec.md
• specs/002-towncrier-release-process/plan.md
• specs/002-towncrier-release-process/tasks.md
• AGENTS.md
• pyproject.toml
• dev/guidelines/git-workflow.md

The release process for the opsmill.infrahub Ansible collection automates version bumping, changelog assembly, and publishing via GitHub Actions and Towncrier. This system replaces hand-maintained CHANGELOG.rst files with news fragments created by contributors during the development of a feature or fix.

The process ensures that every release carries human-written notes while maintaining consistency between versioning files like galaxy.yml and pyproject.toml.

Sources: specs/002-towncrier-release-process/spec.md:14-25, dev/guides/releasing-the-collection.md:4-10

Release Lifecycle

The release lifecycle follows a structured flow from development on the develop branch to a reviewable release pull request (PR) on stable, and finally to publication on Ansible Galaxy.

Release Workflow Overview

The following diagram illustrates the transition from a contributor's change to a published release.

The diagram shows the progression from a PR with fragments to the final Galaxy publication.
Sources: dev/guides/releasing-the-collection.md:12-65, specs/002-towncrier-release-process/plan.md:12-20

Key Release Components

Component	Responsibility
Towncrier	Assembles CHANGELOG.md from news fragments at release time.
News Fragments	One-line Markdown files in changelog/ describing a specific change.
trigger-push-stable.yml	Workflow that computes version, builds changelog, and opens the release PR.
release-publish.yml	Workflow that tags the release and triggers Galaxy upload upon merging the release PR.
galaxy.yml	Canonical source of truth for the collection version.
pyproject.toml	Secondary version file that must be mirrored with galaxy.yml.

Sources: specs/002-towncrier-release-process/plan.md:28-40, specs/002-towncrier-release-process/spec.md:105-117, dev/guidelines/git-workflow.md:21-31

News Fragments & Changelog Management

Every pull request that changes behavior must include a news fragment. If a PR lacks a fragment and does not carry the ci/skip-changelog label, the CI changelog-check.yml will fail.

News Fragment Specification

Fragments are stored in the changelog/ directory. They follow a specific naming convention: <id>.<type>.md. If no issue or PR number is available, an orphan prefix + is used: +<slug>.<type>.md.

Standard Fragment Types:

• security: Security-related changes.
• removed: Deprecated features that were removed.
• deprecated: Features marked for future removal.
• added: New features or modules.
• changed: Changes to existing functionality.
• fixed: Bug fixes.
• housekeeping: Maintenance tasks.

Sources: specs/002-towncrier-release-process/spec.md:105-110, AGENTS.md:55-63, pyproject.toml:343-380

Towncrier Configuration

Towncrier is configured in pyproject.toml. It uses a specific Markdown template and target file.

[tool.towncrier]
directory = "changelog"
filename = "CHANGELOG.md"
start_string = "<!-- towncrier release notes start -->\n"
title_format = "## [Infrahub Ansible - {version}](https://github.com/opsmill/infrahub-ansible/tree/%7Bversion%7D) - {project_date}"
issue_format = "[#{issue}](https://github.com/opsmill/infrahub-ansible/issues/%7Bissue%7D)"
orphan_prefix = "+"
template = "changelog/towncrier.md.template"

Sources: pyproject.toml:330-341, specs/002-towncrier-release-process/tasks.md:25-30

Release Preparation Procedure

Maintainers trigger the release process manually after merging develop into stable.

Steps to Prepare a Release

1. Merge develop to stable: Open and merge a PR targeting the stable branch.
2. Dispatch Workflow: Go to Actions → Push on stable → Run workflow. Select stable as the branch.
3. Version Computation: Leave the version input empty to allow version-drafter-action to compute the next semver bump based on PR labels (e.g., changes/minor).
4. Automatic Processing:
   • The workflow updates pyproject.toml and galaxy.yml.
   • towncrier build consumes news fragments and updates CHANGELOG.md.
   • A new PR named chore(release): <version> is opened.

Sources: dev/guides/releasing-the-collection.md:15-38, specs/002-towncrier-release-process/spec.md:52-65

Automation Logic

The following sequence diagram describes the interaction during the release preparation dispatch.

The diagram shows how user dispatch leads to the creation of a reviewable release PR.
Sources: dev/guides/releasing-the-collection.md:15-38, specs/002-towncrier-release-process/plan.md:12-20

Publishing to Ansible Galaxy

Publishing is triggered by the creation of a GitHub Release, which occurs when the chore(release): <version> PR is merged into stable.

1. Release PR Merge: Merging the release PR triggers .github/workflows/release-publish.yml.
2. Tagging: The workflow creates a bare git tag (e.g., 1.8.3) matching the version in galaxy.yml.
3. GitHub Release: A GitHub Release is created using the Towncrier-rendered changelog section as the body.
4. Galaxy Upload: The release: published event triggers workflow-publish.yml, which builds the collection tarball and uploads it to Ansible Galaxy using INFRAHUB_GALAXY_API_TOKEN.

Sources: dev/guides/releasing-the-collection.md:47-60, specs/002-towncrier-release-process/spec.md:66-72

Summary

The opsmill.infrahub release process centralizes changelog management through Towncrier and enforces a reviewable release PR stage. By utilizing PR labels for versioning and news fragments for notes, the system eliminates manual errors and ensures that every release is documented and auditable before it reaches Ansible Galaxy.

Sources: specs/002-towncrier-release-process/spec.md:120-130, dev/guides/releasing-the-collection.md:83-95