Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add calver transition document #164

Merged
merged 3 commits into from
Jan 23, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.