Releasing collections with release branches
Collections MUST follow the semantic versioning rules. See Releasing collections for high-level details.
Release planning and announcement
Announce your intention to release the collection in a corresponding pinned release issue/community pinboard of the collection and in the
#ansible-community
Matrix/IRC channel. Repeat the announcement in any other dedicated channels if they exist.Ensure all the other repository maintainers are informed about the time of the following release.
Releasing major collection versions
The new version is assumed to be X.0.0
.
Make sure that
galaxy.yml
contains the correct version numberX.0.0
. If that is not the case, create a PR to update it. This will make sanity tests fail for all deprecations that have to be removed inX.0.0
, so this is potentially a lot of work and should have been done weeks before the major release.Check the collection for deprecations that are planned for removal in the major release that were not reported by the sanity tests. Use past changelogs or run
grep -r `X.0.0` plugins/
in the repository.If you are going to release the
community.general
andcommunity.network
collections, create a newbackport-X
label in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels.Ensure you are in a default branch in your local fork. These examples use
main
.
git status git checkout main # if needed
Update your local fork:
git pull --rebase upstream main
Creating the release branch
Create a branch
stable-X
. ReplaceX
with a correct number and push it to the upstream repository, NOT to theorigin
.:
git branch stable-X main git push upstream stable-X
Create and checkout to another branch from the
main
branch:
git checkout -b update_repo
Update the version in
galaxy.yml
in the branch to the next expected version, for example,X.1.0
.
Creating the changelogs
Replace
changelogs/changelog.yml
with:
ancestor: X.0.0 releases: {}
Remove all changelog fragments from
changelogs/fragments/
. Removing the changelog fragments ensures that every major release has a changelog describing changes since the last major release.Add and commit all the changes made. Push the branch to the
origin
repository.Create a pull request in the collection repository. If CI tests pass, merge the pull request since the
main
branch is expecting changes for the next minor/major versionsSwitch to the
stable-X
branch.In the
stable-X
branch, verify thatgalaxy.yml
contains the correct version numberX.0.0
.In the
stable-X
branch, ensure thatchangelogs/changelog.yml
contains a correct ancestor’s version:
ancestor: X-1.0.0 releases: {}
In the
stable-X
branch, add a changelog fragmentchangelogs/fragments/X.0.0.yml
with the 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 inserted into the changelog.For example:
release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD.
In the
stable-X
branch, generate the changelogs:
antsibull-changelog release --cummulative-release
In the
stable-X
branch, verify that theCHANGELOG.rst
looks as expected.In the
stable-X
branch, updateREADME.md
so that the changelog link points to/tree/stable-X/
and no longer to/tree/main/
, and change badges respectively, for example, in case of AZP, 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 toREADME.md
,CHANGELOG.rst
andchangelogs/changelog.yaml
, and potentially deleted/archived fragments to the upstream repository, NOT to theorigin
.
Publishing the collection
In the
stable-X
branch, add an annotated tag to the last commit with the collection versionX.0.0
. Pushing this tag to theupstream
repository will make Zuul publish the collection on Ansible Galaxy.
git tag -n # see current tags and their comments git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" git push upstream NEW_VERSION
If the collection uses Zuul for publishing its releases, wait until the new version is published on the collection’s Ansible Galaxy page. It will appear in a list of tarballs available to download.
If the release tarball did not appear within several hours after pushing the tag, try to re-tag the release commit and push the tag again. In the
stable-X
branch being at the release commit:
git tag --delete NEW_VERSION git push upstream :NEW_VERSION git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" git push upstream NEW_VERSION
Add a GitHub release for the new tag. The title should be the version and content, such as -
See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes
.Announce the release through the Bullhorn Newsletter.
Announce the release in the pinned release issue/community pinboard of the collection and in the
#ansible-community
Matrix/Libera.Chat IRC channel.In the
stable-X
branch, update the version ingalaxy.yml
to the next expected version, for example,X.1.0
. Add, commit and push to the upstream repository.
Releasing minor collection versions
The new version is assumed to be X.Y.0
. All changes that should go into it are expected to be previously backported from the default branch to the stable-X
branch.
Creating the changelogs
In the
stable-X
branch, make sure thatgalaxy.yml
contains the correct version numberX.Y.0
. If not, update it.In the
stable-X
branch, add a changelog fragmentchangelogs/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 inserted into the changelog.
In the
stable-X
branch, run:
antsibull-changelog release
In the
stable-X
branch, verify thatCHANGELOG.rst
looks as expected.In the
stable-X
branch, add, commit, and push changes toCHANGELOG.rst
andchangelogs/changelog.yaml
, and potentially deleted/archived fragments to the upstream repository, NOT to the origin.
Publishing the collection
In the
stable-X
branch, add an annotated tag to the last commit with the collection versionX.Y.0
. Pushing this tag to theupstream
repository will make Zuul publish the collection on Ansible Galaxy.
git tag -n # see current tags and their comments git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.0" git push upstream NEW_VERSION
Wait until the new version is published on the collection’s Ansible Galaxy page. The published version will appear in a list of tarballs available to download.
Add a GitHub release for the new tag. The title should be the version and content, such as -
See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes
.Announce the release through the Bullhorn Newsletter.
Announce the release in the pinned release issue/community pinboard of the collection and in the
#ansible-community
Matrix/IRC channel. Additionally, you can announce it using GitHub’s Releases system.In the
stable-X
branch, update the version ingalaxy.yml
to the next expected version, for example, if you have releasedX.1.0
, the next expected version could beX.2.0
. Add, commit and push to the upstream repository.Checkout to the
main
branch.In the
main
branch:
If more minor versions are released before the next major version, update the version in
galaxy.yml
toX.(Y+1).0
as well. Create a dedicated pull request and merge.If the next version will be a new major version, create a pull request 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. For example, you remove the complete
modules/plugins
or you remove redirects.Whether to add ignore entries to the corresponding
tests/sanity/ignore-*.txt
file and create issues, for example for removed features inmodules/plugins
.Once the CI tests pass, merge the pull request. Make sure that this pull request is merged not too much later after the release for
version_added
sanity tests not to expect the wrong version for the new feature pull request.
Note
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.
Releasing patch versions
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
. z
is frequently 0
since patch releases are uncommon.
Releasing when more minor versions are expected
Checkout the
X.Y.z
tag.Update
galaxy.yml
so that the version isX.Y.Z
. Add and commit.Cherry-pick all changes from
stable-X
that were added afterX.Y.z
and should go intoX.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 inserted into the changelog.Add to Git and commit.
Generate the changelogs.
antsibull-changelog release
Verify that
CHANGELOG.rst
looks as expected.Add and commit changes to
CHANGELOG.rst
andchangelogs/changelog.yaml
, and potentially deleted/archived fragments.
Publishing the collection
Add an annotated tag to the last commit with the collection version
X.Y.Z
. Pushing this tag to theupstream
repository will make Zuul publish the collection on Ansible Galaxy.
git tag -n # see current tags and their comments git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.1" git push upstream NEW_VERSION
Wait until the new version is published on the collection’s Ansible Galaxy page. It will appear in a list of tarballs available to download.
Add a GitHub release for the new tag. The title should be the version and content, such as -
See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes
.
Note
The data for this release is only contained in a tag, and not in a branch, in particular not in
stable-X
. This is deliberate, since the next minor releaseX.(Y+1).0
already contains the changes forX.Y.Z
as well since these were cherry-picked fromstable-X
.
Announce the release through the Bullhorn Newsletter.
Announce the release in the pinned release issue/community pinboard of the collection and in the
#ansible-community
Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>.
Releasing when no more minor versions are expected
In the
stable-X
branch, make sure thatgalaxy.yml
contains the correct version numberX.Y.Z
. If not, update it!In the
stable-X
branch, add a changelog fragmentchangelogs/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 inserted into the changelog.
Generate the changelogs in the
stable-X
branch.
antsibull-changelog release
In the
stable-X
branch, verify thatCHANGELOG.rst
looks as expected.In the
stable-X
branch, add, commit, and push changes toCHANGELOG.rst
andchangelogs/changelog.yaml
, and potentially deleted/archived fragments to the upstream repository, NOT to the origin.
Publishing the collection
In the
stable-X
branch, add an annotated tag to the last commit with the collection versionX.Y.Z
. Pushing this tag to theupstream
repository will make Zuul publish the collection on Ansible Galaxy.
git tag -n # see current tags and their comments git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.1" git push upstream NEW_VERSION
Wait until the new version is published on the collection’s Ansible Galaxy page. It will appear in a list of tarballs available to download.
Add a GitHub release for the new tag. Title should be the version and content, such as:
See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes
.Announce the release through the Bullhorn Newsletter.
Announce the release in the pinned issue/community pinboard of the collection and in the
#ansible-community
Matrix/IRC channel.