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.

Remember that all the changes from the following instructions must eventually be made in main branch and pushed into upstream (NOT into origin as usual). So if you made them in another branch, don't forget to merge it to main before pushing.

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.
Add, commit and push changes to CHANGELOG.rst and changelogs/changelog.yaml, and potentially deleted/archived fragments.
Add a tag to the last commit with the collection version. Pushing this tag will make Zuul publish the collection.
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.

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.
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.)
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 text: This is release X.0.0 of ``community.xxx``, released on 2020-xx-xx.

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.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.
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.
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. Do not 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.
Write an announcement to the corresponding issue. Do not update the next expected release, since this is reserved for major and minor releases.
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..