From 8f4779a4d5fc640403fb639addafd31dadc6bcbb Mon Sep 17 00:00:00 2001 From: Kate Case Date: Tue, 23 Jan 2024 08:10:06 -0500 Subject: [PATCH] Add calver transition document --- docs/guides/calver-transition.md | 67 ++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/guides/calver-transition.md diff --git a/docs/guides/calver-transition.md b/docs/guides/calver-transition.md new file mode 100644 index 0000000..6e9ae18 --- /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 + + When looking at a version number, there's no good way of telling how old it is + without looking up the release notes. + +* 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 features and removals by category, including +minor and major features, 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.