ReleasingCollections

Releasing without Release Branches (for "smaller" collections)

These instructions assume that publishing the collection is done via Zuul, and that antsibull-changelog is used for the changelog. Since no release branches are used, the instructions do not distinguish between releasing a major, minor or patch version.

1. Make sure that galaxy.yml contains the correct version number. If not, update it!
2. Add a changelog fragment changelogs/fragments/X.Y.Z.yml with content:

   release_summary: |
     Write some text here that should appear as the release summary for this version.
     The format is reStructuredText (but not a list as for regular changelog fragments).
     This text will be verbatimly inserted into the changelog.

   Add to git and commit.
3. Run antsibull-changelog release (should previously be installed by pip install antsibull-changelog).
4. Verify that CHANGELOG.rst looks good.
5. Add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
6. Add a tag to the last commit with the collection version. Pushing this tag will make Zuul publish the collection.
7. Update the version in galaxy.yml to the next (expected) version. Add, commit and push.

Releasing with Release Branches (for example community.general and community.network)

These instructions assume that publishing the collection is done via Zuul, and that antsibull-changelog is used for the changelog.

Announcements are made in the issues https://github.com/ansible-collections/community.general/issues/582 and https://github.com/ansible-collections/community.network/issues/81.

Releasing Major Versions

The new version is assumed to be X.0.0.

1. Create a branch stable-X and push to the repository.

2. Update the version in galaxy.yml in the main branch to the next (expected) version. For community.general and community.network, it will be X.1.0. Add, commit and push. From this point on, the main branch is expecting changes for the next minor/major versions.

3. If X > 1, replace changelogs/changelog.yaml with:

   ancestor: X.0.0
   releases: {}

   Add, commit and push.

   (This ensures that every major release has a changelog describing changes since the last major release.)

4. Now switch back to the stable-X branch.

5. In the stable-X branch, make sure that galaxy.yml contains the correct version number X.0.0. If not, update it!

6. In the stable-X branch, add a changelog fragment changelogs/fragments/X.0.0.yml with content:

   release_summary: |
     Write some text here that should appear as the release summary for this version.
     The format is reStructuredText (but not a list as for regular changelog fragments).
     This text will be verbatimly inserted into the changelog.

   Add to git and commit.

   Suggestion for text: This is release X.0.0 of ``community.xxx``, released on 2020-xx-xx.

7. In the stable-X branch, run antsibull-changelog release.

8. In the stable-X branch, verify that CHANGELOG.rst looks good.

9. In the stable-X branch, add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.

10. In the stable-X branch, add a tag to the last commit named X.0.0. Pushing this tag will make Zuul publish the collection.

11. In the stable-X branch, update the version in galaxy.yml to the next (expected) version, i.e. X.1.0. Add, commit and push.

12. Write an announcement to the corresponding issue, and update the next (expected) version there.

13. Add GitHub release for this tag. Title should be the version, and content See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes..

Releasing Minor Versions

The new version is assumed to be X.Y.0. All changes that should go into it are expected to be in the stable-X branch (cherry-picked from main, either manually or by bot).

1. In the stable-X branch, make sure that galaxy.yml contains the correct version number X.Y.0. If not, update it!
2. In the stable-X branch, add a changelog fragment changelogs/fragments/X.Y.0.yml with content:

   release_summary: |
     Write some text here that should appear as the release summary for this version.
     The format is reStructuredText (but not a list as for regular changelog fragments).
     This text will be verbatimly inserted into the changelog.

   Add to git and commit.
3. In the stable-X branch, run antsibull-changelog release.
4. In the stable-X branch, verify that CHANGELOG.rst looks good.
5. In the stable-X branch, add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
6. In the stable-X branch, add a tag to the last commit named X.Y.0. Pushing this tag will make Zuul publish the collection.
7. In the stable-X branch, update the version in galaxy.yml to the next (expected) version, i.e. X.(Y+1).0. Add, commit and push.
8. In the main branch, update the version in galaxy.yml to X.(Y+1).0 as well. Add, commit and push.
9. Write an announcement to the corresponding issue, and update the next (expected) version there.
10. Add GitHub release for this tag. Title should be the version, and content See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes..

Releasing Patch Versions (more minor versions expected)

The new version is assumed to be X.Y.Z, and the previous patch version is assumed to be X.Y.z with z < Z (probably z is 0, as patch releases should be uncommon).

This is a bit more complicated, since the stable-X branch potentially already contains commits that should not go into a patch release.

1. Checkout the X.Y.z tag.
2. Update galaxy.yml so that the version is X.Y.Z. Add and commit.
3. Cherry-pick all changes from stable-X that were added after X.Y.z and should go into X.Y.Z.
4. Add a changelog fragment changelogs/fragments/X.Y.Z.yml with content:

   release_summary: |
     Write some text here that should appear as the release summary for this version.
     The format is reStructuredText (but not a list as for regular changelog fragments).
     This text will be verbatimly inserted into the changelog.

   Add to git and commit.
5. Run antsibull-changelog release.
6. Verify that CHANGELOG.rst looks good.
7. Add and commit changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
8. Add a tag to the last commit named X.Y.Z. Pushing this tag will make Zuul publish the collection.
9. Write an announcement to the corresponding issue. Do not update the next expected release.
10. Add GitHub release for this tag. Title should be the version, and content See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes..

The data for this release is only contained in a tag, and not in a branch (in particular not in stable-X). This is intended, since the next minor release X.(Y+1).0 already contains the changes for X.Y.Z as well (since these were cherry-picked from stable-X).

Releasing Patch Versions (no more minor versions planned)

The new version is assumed to be X.Y.Z, and the previous patch version is assumed to be X.Y.z with z < Z (probably z is 0, as patch releases should be uncommon).

1. In the stable-X branch, make sure that galaxy.yml contains the correct version number X.Y.Z. If not, update it!
2. In the stable-X branch, add a changelog fragment changelogs/fragments/X.Y.Z.yml with content:

   release_summary: |
     Write some text here that should appear as the release summary for this version.
     The format is reStructuredText (but not a list as for regular changelog fragments).
     This text will be verbatimly inserted into the changelog.

   Add to git and commit.
3. In the stable-X branch, run antsibull-changelog release.
4. In the stable-X branch, verify that CHANGELOG.rst looks good.
5. In the stable-X branch, add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
6. In the stable-X branch, add a tag to the last commit named X.Y.Z. Pushing this tag will make Zuul publish the collection.
7. In the stable-X branch, update the version in galaxy.yml to the next (expected) version, i.e. X.Y.(Z+1). Add, commit and push.
8. Write an announcement to the corresponding issue. Do not update the next expected release, since this is reserved for major and minor releases.
9. Add GitHub release for this tag. Title should be the version, and content See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes..