ansible-podman-collections/RELEASING.md

Releasing a New Version

This document describes how to release a new version of the containers.podman collection.

Step 1: Update the Changelog

Add a new section for the release tag in changelogs/changelog.yaml. Include all user-facing changes since the previous release — bugfixes, new features, new modules, breaking changes, etc. Skip maintenance-only changes like CI improvements, test infrastructure updates, or internal refactoring that don't affect users.

Each release entry follows this format:

  X.Y.Z:
    changes:
      release_summary: Short summary of the release
      bugfixes:
        - podman_container - Description of the fix
      minor_changes:
        - podman_image - Description of the change
      major_changes:
        - Description of major change
    # Include 'modules' section only when new modules are added:
    modules:
      - description: What the module does
        name: module_name
        namespace: ''
    # Include 'plugins' section only when new plugins are added
    release_date: 'YYYY-MM-DD'

Valid change categories: release_summary, major_changes, minor_changes, breaking_changes, deprecated_features, removed_features, security_fixes, bugfixes, known_issues.

Step 2: Update the Version in galaxy.yml

Set the new version:

sed -i 's/^version: .*/version: X.Y.Z/' galaxy.yml

This updates the version field directly in galaxy.yml.

Step 3: Generate the CHANGELOG

Run:

antsibull-changelog release

This reads changelogs/changelog.yaml and regenerates CHANGELOG.rst.

Step 4: Update Documentation (Major Releases Only)

For major releases (e.g., 1.18.0 -> 1.19.0), regenerate the documentation:

1. If new modules were added, git add their generated doc files first.

2. Run:

   contrib/build_docs.sh [output_dir]
   

   The default output directory is $HOME/podman-docs. The script builds the collection, installs it to a temp path, and runs antsibull-docs + Sphinx to generate HTML docs.

Skip this step for patch/minor releases (e.g., 1.19.0 -> 1.19.1).

Step 5: Create a PR

Create a branch with the changelog, galaxy.yml, and CHANGELOG.rst changes (plus docs if applicable), then open a PR:

git checkout -b release-X.Y.Z
git add changelogs/changelog.yaml galaxy.yml CHANGELOG.rst
git commit -m "Release X.Y.Z"
git push origin release-X.Y.Z

Step 6: Tag and Publish

After the PR is merged to main, tag the merge commit with the release version:

git tag X.Y.Z
git push origin X.Y.Z

The tag push triggers the collection-publish.yml GitHub Actions workflow, which automatically builds and publishes the collection to Ansible Galaxy. The tag must match the pattern [0-9]+.[0-9]+.[0-9]+.