Skip to content

Commit

Permalink
Add calver transition document (#164)
Browse files Browse the repository at this point in the history
* Add calver transition document

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Clarify wording of release age and release notes categories

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
Qalthos and pre-commit-ci[bot] authored Jan 23, 2024
1 parent 29ddf2f commit 6f5a00e
Showing 1 changed file with 67 additions and 0 deletions.
67 changes: 67 additions & 0 deletions docs/guides/calver-transition.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 6f5a00e

Please sign in to comment.