Debian Codegraph @

ansible_collections/containers/podman/RELEASING.md

raw
1 # Releasing a New Version
2
3 This document describes how to release a new version of the `containers.podman` collection.
4
5 ## Step 1: Update the Changelog
6
7 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.
8
9 Each release entry follows this format:
10
11 ```yaml
12 X.Y.Z:
13 changes:
14 release_summary: Short summary of the release
15 bugfixes:
16 - podman_container - Description of the fix
17 minor_changes:
18 - podman_image - Description of the change
19 major_changes:
20 - Description of major change
21 # Include 'modules' section only when new modules are added:
22 modules:
23 - description: What the module does
24 name: module_name
25 namespace: ''
26 # Include 'plugins' section only when new plugins are added
27 release_date: 'YYYY-MM-DD'
28 ```
29
30 Valid change categories: `release_summary`, `major_changes`, `minor_changes`, `breaking_changes`, `deprecated_features`, `removed_features`, `security_fixes`, `bugfixes`, `known_issues`.
31
32 ## Step 2: Update the Version in galaxy.yml
33
34 Set the new version:
35
36 ```bash
37 sed -i 's/^version: .*/version: X.Y.Z/' galaxy.yml
38 ```
39
40 This updates the version field directly in `galaxy.yml`.
41
42 ## Step 3: Generate the CHANGELOG
43
44 Run:
45
46 ```bash
47 antsibull-changelog release
48 ```
49
50 This reads `changelogs/changelog.yaml` and regenerates `CHANGELOG.rst`.
51
52 ## Step 4: Update Documentation (Major Releases Only)
53
54 For major releases (e.g., 1.18.0 -> 1.19.0), regenerate the documentation:
55
56 1. If new modules were added, `git add` their generated doc files first.
57 2. Run:
58
59 ```bash
60 contrib/build_docs.sh [output_dir]
61 ```
62
63 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.
64
65 Skip this step for patch/minor releases (e.g., 1.19.0 -> 1.19.1).
66
67 ## Step 5: Create a PR
68
69 Create a branch with the changelog, galaxy.yml, and CHANGELOG.rst changes (plus docs if applicable), then open a PR:
70
71 ```bash
72 git checkout -b release-X.Y.Z
73 git add changelogs/changelog.yaml galaxy.yml CHANGELOG.rst
74 git commit -m "Release X.Y.Z"
75 git push origin release-X.Y.Z
76 ```
77
78 ## Step 6: Tag and Publish
79
80 After the PR is merged to `main`, tag the merge commit with the release version:
81
82 ```bash
83 git tag X.Y.Z
84 git push origin X.Y.Z
85 ```
86
87 The tag push triggers the `collection-publish.yml` GitHub Actions workflow, which automatically builds and publishes the collection to [Ansible Galaxy](https://galaxy.ansible.com/containers/podman). The tag must match the pattern `[0-9]+.[0-9]+.[0-9]+`.