ReleasingCollections - ansible/community GitHub Wiki

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.

Be sure you are in a default branch in your local fork:
```
git checkout DEFAULT_BRANCH
```

Update your local fork:

git pull --rebase upstream DEFAULT_BRANCH

Checkout a new release branch from main:
```
git checkout -b release_branch
```
Make sure that galaxy.yml contains the correct version number. If not, update it!

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.

If the content was recently moved from another collection, be sure you have all related changelog fragments in changelogs/fragments directory. If not, copy them previously.
Run antsibull-changelog release (should previously be installed by pip install antsibull-changelog).
Verify that CHANGELOG.rst looks good.
Commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments to origin repository's release_branch.
```
git commit -a -m "Release VERSION commit"
git push origin release_branch
```
Create a pull request in the collection repository. If CI tests pass, merge it.

Checkout the default branch and pull the changes:

git checkout DEFAULT_BRANCH
git pull --rebase upstream DEFAULT_BRANCH

Add an annotated tag to the release commit with the collection version. Pushing this tag to upstream will make Zuul publish the collection.

git tag -n  # see current tags and their comments
git tag -a NEW_VERSION -m "comment here"  # comment can be, for example, "community.postgresql: 1.2.0"
git push upstream NEW_VERSION

Update the version in galaxy.yml to the next (expected) version. Add, commit and push to upstream's main branch.

NOTE For repositories using AZP, only push once AZP has started for the previously pushed commit. Otherwise, due to pushing several commits in a row, AZP's batch feature might skip CI for the release commit - which violates the requirements (background).
Put a note about the release in https://github.com/ansible/community/issues/546 to have it published by the Bullhorn newsletter.

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.

Create a branch stable-X and push to the repository.
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.
In community.general and community.network, create new labels backport-X and needs_backport_to_stable_X. Copy the styles and descriptions from the corresponding X-1 labels.
Replace changelogs/changelog.yaml with:
```
ancestor: X.0.0
releases: {}
```
Also remove all changelog fragments from changelogs/fragments/. Add, commit and push.

(This ensures that every major release has a changelog describing changes since the last major release.)
Now switch back to the stable-X branch.
In the stable-X branch, make sure that galaxy.yml contains the correct version number X.0.0. If not, update it!

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 the fragment:

release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD.

In the stable-X branch, run antsibull-changelog release --cummulative-release.
In the stable-X branch, verify that CHANGELOG.rst looks good.
In the stable-X branch, update README.md so that the changelog link points to /tree/stable-X/ and no longer to /tree/main/, and add ?branchName=stable-X to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X).
In the stable-X branch, add, commit and push changes to README.md, CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
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.
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.

NOTE For repositories using AZP, only push once AZP has started for the previously pushed commit. Otherwise, due to pushing several commits in a row, AZP's batch feature might skip CI for the release commit - which violates the requirements (background).
Write an announcement to the corresponding issue, and update the next (expected) version there.
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).

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

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.

In the stable-X branch, run antsibull-changelog release.
In the stable-X branch, verify that CHANGELOG.rst looks good.
In the stable-X branch, add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
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.
In the stable-X branch, update the version in galaxy.yml to the next (expected) version, i.e. X.(Y+1).0, or X.Y.1 if no more minor releases will be made. Add, commit and push.

NOTE For repositories using AZP, only push once AZP has started for the previously pushed commit. Otherwise, due to pushing several commits in a row, AZP's batch feature might skip CI for the release commit - which violates the requirements (background).
In the main branch:
1. If more minor versions are released before the next major version, update the version in galaxy.yml to X.(Y+1).0 as well. Add, commit and push.
2. If the next version will be a new major version, create a PR where you update the version in galaxy.yml to (X+1).0.0. Note that the sanity tests will most likely fail since there will be deprecations with removal scheduled for (X+1).0.0, which are flagged by the tests.
  
  For every such deprecation, decide whether to remove them now (makes sense if complete modules/plugins are removed, or redirects are removed), or whether to add ignore.txt entries and create issues (makes sense for removed features in modules/plugins). Once CI passes, merge. Make sure that this PR is merged not too much later after the release for verison_added sanity tests to not expect the wrong version for new feature PRs.
  
  (It makes sense to already do some removals in the days before the release. These removals must happen in the main branch and must not be backported.)
Write an announcement to the corresponding issue, and update the next (expected) version there.
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.

Checkout the X.Y.z tag.
Update galaxy.yml so that the version is X.Y.Z. Add and commit.
Cherry-pick all changes from stable-X that were added after X.Y.z and should go into X.Y.Z.

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.

Run antsibull-changelog release.
Verify that CHANGELOG.rst looks good.
Add and commit changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
Add a tag to the last commit named X.Y.Z. Pushing this tag will make Zuul publish the collection.
Write an announcement to the corresponding issue. Also update the next expected release.
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).

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

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.

In the stable-X branch, run antsibull-changelog release.
In the stable-X branch, verify that CHANGELOG.rst looks good.
In the stable-X branch, add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
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.
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.

NOTE For repositories using AZP, only push once AZP has started for the previously pushed commit. Otherwise, due to pushing several commits in a row, AZP's batch feature might skip CI for the release commit - which violates the requirements (background).
Write an announcement to the corresponding issue. Also update the next expected release.
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..