diff --git a/docs/guides/calver-transition.md b/docs/guides/calver-transition.md new file mode 100644 index 0000000..950774b --- /dev/null +++ b/docs/guides/calver-transition.md @@ -0,0 +1,67 @@ +# Devtools Projects Transitioning to CalVer Releases + +Projects in the devtools space will be switching to [CalVer](https://calver.org/) +releases over the next few weeks. This is a surprising change, so let's get into +what that means. + +## What + +These are the projects that will be transitioning to CalVer: + +- ansible-compat +- ansible-creator +- ansible-dev-environment +- ansible-lint +- ansible-navigator +- creator-ee +- molecule +- pytest-ansible +- tox-ansible +- vscode-ansible + +We will use a `YY.MM.MICRO` version format. Thus, a release for March 2025 will be +named `25.3.0`, and if a patch (ie, non-feature) release is required for that release, +it will be named `25.3.1`, even if it is released in April, and the month will not +increment until a new version with features or other significant changes is released. + +## Why + +This is a bit of a change so let's go over what we hope to accomplish with it. + +- Predictable, transparent release cadence + + With this, we are committing to time-based releases for all projects. + While the exact frequency will vary between projects, each will have a release + between one and three months after the last feature release. + +- Version number indicates the age of a release + + With CalVer, the age of a release can be trivially determined from the version + number, instead of having to look up the release notes as at present. + +- Easier to translate versions between tools + + Many of our tools are interrelated. A consistent version scheme allows one to + have a good idea of how related but independent tools are expected to work together. + +## How + +Following this announcement, the next feature release in each project will +be a CalVer release. + +Feature releases will not happen more often than once a month, though +patch releases may happen more often as needed. We will also make +releases at least once every three months for each project. + +Releases will still split out changes by category, including new features, +bugfixes, documentation updates, announced deprecations, and removed features. + +One of the things we are bringing with this change is an emphasis on fewer +breaking changes / more emphasis on deprecation cycles and overlapping features. +When something is deprecated, it will be called out in the release notes, along +with replacement and how long the feature will remain in place. + +## What's Next + +As mentioned, this change will begin rolling out over the next few weeks. However, +if you have any comments or concerns, please let us know.