Releasing, Versioning and Deprecation

lonico commented 3 years ago

Introduction

This issue describes how and when netapp collections are released, and to announce updates to the release/versioning schedule. Other changes to this first post are always announced by separate posts in this issue.

Versioning schema

Until April 2021, releases are numbered as YY.M.P or YY.MM.P.

YY is the year, eg 21 for 2021
M or MM is the month, 1 to 12 (leading 0 is not allowed) - for simplification, we will use MM below.
P is the patch number. A 0 indicates the first minor release of the month, P > 0 indicates a patch release.

Starting in April, we are switching to semantic versioning as M.m.p

M is the major version, currently 21.
m is the minor version, currently 4.
p is the patch number, with a value of 0 for the initial release.

You can see that for 2021, the two versioning schemas overlap.

But we already released 21.5.0 as of April 22, and 21.6.0 as of May 06.

Releasing schedule for major and minor versions

Our intent is to release collection updates on the first Wednesday of every month. The collections that are active as of April 2021 are CloudManager and ONTAP, and are most likely to see regular updates. Other collections will only be updated if a feature request or a non urgent bug fix is ready for this month. If no new commit has been merged for a minor release, it must be skipped.

We strive to maintain backwards compatibility. If there is a strong enough justification, we will increase the Major release number to indicate a chance of a breaking change.

Releasing schedule for patch versions

If possible, we will wait for the next minor release. If we deem the fix urgent, we will release a patch version as MM.m.p with z > 0.

Versioning

galaxy.yml in the master branch will always contain the version of the next minor release. It will be updated right after a release. version_added needs to be used for every new feature and module/plugin, and needs to coincide with the next minor/major release version. (This is enforced by our internal CI.)

Branching

Releasing major or minor releases is done from a tagged master branch. New features must not break backwards compatibility. If there is a strong enough justification, we will increase the Major release number to indicate a chance of a breaking change.

Backporting process

We do not backport any change. As new versions maintain backward compatibility, it is always possible to move to a new minor version. If we introduce a major change, we may revisit this statement.

Deprecation

Deprecations are done by version number (not by date). New deprecations can be added during every minor release, under the condition that they do not break backwards compatibility. Deprecations are expected to have a deprecation cycle of at least 1 year.

Changelogs

Every change that does not only affect docs or tests must have a changelog fragment. Exception: fixing/extending a feature that already has a changelog fragment and has not yet been released. Such PRs must always link to the original PR(s) they update. Use your common sense!

Fragments must not be added for new module PRs and new plugin PRs. The only exception are test and filter plugins: these are not automatically documented yet.

Changelogs do not contain previous major releases, and only use the ancestor feature (in changelogs/changelog.yaml) to point to the previous major release.

Changelog fragments are removed after a release is made.

anshulbehl commented 3 years ago

@lonico Thanks a lot for documenting this, for the below quote

For example, if everything goes according to plan, the community will release Ansible 5.0.0 sometime near the end of 2021. Collections will be pinned at that time to the latest major version available, which in your case will be 21.x.y. If you find a bug in one of your collections in January 2022 and release it as 22.z.u, Ansible users will have to wait almost half a year to get that bugfix if they do not want to manually install the collection from Ansible Galaxy.

Do you have a way to document how you will handle the above scenario, like if this happens your customers can probably manually update the collections on their system to latest release. That way community team would know that you have documented the scenarios and users will also know what they need to do. cc: @thedoubl3J @gundalow @carchi8py

gundalow commented 3 years ago

Missing Tags in GitHub

https://galaxy.ansible.com/netapp/ontap lists 21.3.0 though I don't see that on https://github.com/ansible-collections/netapp/tags

thedoubl3j commented 3 years ago

@gundalow @anshulbehl Would we want this documented at the collection level (in a md file) or is the issue fine? I think if a reference is made to the issue pointing at it as the source of truth for release/version/deprecation info then I am fine but could understand why it might be better served in a doc at the top level of the repo (not technically needed in each collection is it as its dev focused?)

carchi8py commented 3 years ago

@gundalow looks like I missed setting that tag, let me go back in our internal repo and find the hash and tag it.

carchi8py commented 3 years ago

The Tag/release has been created

gundalow commented 3 years ago

@gundalow @anshulbehl Would we want this documented at the collection level (in a md file) or is the issue fine? I think if a reference is made to the issue pointing at it as the source of truth for release/version/deprecation info then I am fine but could understand why it might be better served in a doc at the top level of the repo (not technically needed in each collection is it as its dev focused?)

@thedoubl3j I think in a README.md would be great, easier for others to find

The Tag/release has been created

@carchi8py Brilliant, thank you. We do have automation

lonico commented 3 years ago

Missing Tags in GitHub

https://galaxy.ansible.com/netapp/ontap lists 21.3.0 though I don't see that on https://github.com/ansible-collections/netapp/tags

Yes, we forgot it. I noticed that Wednesday, for our internal repo. I had to use 21.3.1, and fortunately, it was off by a single commit. But Chris got it fixed on GitHub. I wonder if there is a way to enforce this, it's currently a manual process.

lonico commented 3 years ago

As of 5/10, we split our single repo hosting 7 collections into 7 repos, each hosting a single collection:

netapp.aws netapp.azure netapp.cloudmanager netapp.elementsw netapp.ontap netapp.storagegrid netapp.um_info

This enables us to version each collection independently. The release notes for each collection identify the release contents for each version.

gundalow commented 3 years ago

@lonico @carchi8py I'd be interested in how you reached the decision to split into separate collections? Those details can help us support future collection owners.

carchi8py commented 3 years ago

@gundalow There were a few things. Originally it was mentioned here https://github.com/ansible-collections/ansible-inclusion/discussions/16#discussioncomment-671886 during the review of the cloudmanager collection.

When we looked in to it, it overall was going to make our lives easier so we decided to make the change to single repo (first internally and then externally in github) for the following reasons

versioning: We might have a new release for 2 of our 7 collections, but since the version on github was shared we'd end up having to skill release in the collection that didn't have update (You can see that here https://github.com/ansible-collections/netapp.um_info (20.5.0, 20.6.0, 21.5.0, 21.6.0). Now each collection its own github, the versioning no longer has to match. Meaning we only increment the version when that collection has a version
pipeline: both the internal pipeline, and the one on GitHub was getting super huge. 7 collections 4 support ansible version = 24 sanity runs on every commit (https://github.com/ansible-collections/netapp/actions/runs/818598451). Our internal one also runs unit test, size check and netapp specific check, that the github one currently does not. Splitting into separate github repo bring this down to 1 collection support ansible version (https://github.com/ansible-collections/netapp.cloudmanager/actions/runs/830588583)
multiple teams: The original collections are developed by my team, but we recently adding Storagegrid collection (which is developed by a different team). Having multiples working on multiple project share the same release and versioning, was starting to become hard.

carchi8py commented 3 years ago

Also we are looking at using github issue template for issue, and for each product there a different set of thing we need form users

ansible-collections / netapp