Skip to content

Commit

Permalink
Update release guidance for Valkey (#94)
Browse files Browse the repository at this point in the history 
A fairly extensive rewrite of the Valkey release and versioning
documentation from our docs. Generally made two significant changes.

1. Made much clearer guidance around semantic versioning and how we
follow it.
2. Made more explicit the support model for how long we maintain a
release.

---------

Signed-off-by: Madelyn Olson <[email protected]>
Co-authored-by: Viktor Söderqvist <[email protected]>
  • Loading branch information
@madolson @zuiderkwast
madolson and zuiderkwast authored Jun 21, 2024
1 parent 81a7559 commit c8644e8
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 102 deletions.
169 changes: 68 additions & 101 deletions topics/releases.md
View file
Original file line number Diff line number Diff line change
@@ -1,141 +1,108 @@
---
title: "Valkey release cycle"
linkTitle: "Release cycle"
description: How are new versions of Valkey released?
title: "Valkey releases and versioning"
linkTitle: "Valkey releases"
description: How new versions of Valkey are released and supported
---

Valkey is system software and a type of system software that holds user data, so
it is among the most critical pieces of a software stack.
Valkey is usually among the most critical pieces of a software stack.
For this reason, Valkey's release cycle prioritizes highly stable releases at the cost of slower release cycles.

For this reason, Valkey's release cycle is such that it ensures highly stable
releases, even at the cost of slower cycles.
All Valkey releases are published in the [Valkey GitHub repository](https://github.com/valkey-io/valkey/releases).

New releases are published in the [Valkey GitHub repository](https://github.com/valkey-io/valkey/releases).

## Release cycle

A given version of Valkey can be at three different levels of stability:

* Unstable
* Release Candidate
* Stable

### Unstable tree

The unstable version of Valkey is located in the `unstable` branch in the
[Valkey GitHub repository](https://github.com/valkey-io/valkey).

This branch is the source tree where most of the new features are under
development. `unstable` is not considered production-ready: it may contain
critical bugs, incomplete features, and is potentially unstable.

However, we try hard to make sure that even the unstable branch is usable most
of the time in a development environment without significant issues.

### Release candidate

New minor and major versions of Valkey begin by branching off the `unstable`
branch. The branch name is the target release on the form *major.minor*.
Subsequent patch releases are made on the same branch.

For example, when Valkey 7.2.5 was released, the release was made on the `7.2`
branch, which had been branched off from `unstable` earlier.
## Versioning

Bug fixes and new features that can be stabilized during the release's time
frame are committed to the unstable branch and backported to the release
candidate branch. The `unstable` branch may include additional work that is not
a part of the release candidate and scheduled for future releases.
Valkey stable releases will generally follow `major.minor.patch` [semantic versioning schema](https://semver.org/).
We follow semantic versioning to provide explicit guarantees regarding backward compatibility.

The first release candidate, or RC1, is released once it can be used for
development purposes and for testing the new version. At this stage, most of
the new features and changes the new version brings are ready for review, and
the release's purpose is collecting the public's feedback.
When discussing compatibility, we refer to the following API contracts:

Subsequent release candidates are released every three weeks or so, primarily
for fixing bugs. These may also add new features and introduce changes, but at
a decreasing rate and decreasing potential risk towards the final release
candidate.
1. Valkey commands including their inputs, outputs, and defined behavior
2. The functions and APIs that can be executed from a Lua script
3. The RDB version
4. The protocol used to establish and replicate data from primaries to replicas
5. The protocol between nodes within a Valkey cluster
6. The Valkey Module API interface
7. The AOF on disk format

### Stable tree
### Patch versions

Once development has ended and the frequency of critical bug reports for the
release candidate wanes, it is ready for the final release. At this point, the
release is marked as stable and is released with "0" as its patch-level
version.
*Patch* versions are released with backwards compatible bug fixes and should not introduce new features.

## Versioning
Upgrading from a previous patch version should be safe and seamless.
It should be safe to run a primary-replica pair or a Valkey cluster with servers running on different patch versions.

Stable releases liberally follow the usual `major.minor.patch` semantic
versioning schema. The primary goal is to provide explicit guarantees regarding
backward compatibility.
*Patch* versions may also introduce small improvements such as performance or memory optimizations that are easy to verify as safe.

### Patch-Level versions
### Minor versions

Patches primarily consist of bug fixes and very rarely introduce any
compatibility issues.
*Minor* versions are released with new functionality that is added in a backward compatible manner.
Examples of new functionality include new commands, info fields, or configuration parameters.

Upgrading from a previous patch-level version is almost always safe and
seamless.
Upgrading from a previous minor version should be safe, and will not introduce incompatibilities between servers in the cluster when default server configurations are used.

New features and configuration directives may be added, or default values
changed, as long as these don’t carry significant impacts or introduce
operations-related issues.
**NOTE:** Minor releases may include new commands and data types that can introduce incompatibility between servers in the cluster, but users need to opt-in to these features to cause this type of incompatibility.
For this reason, it is not recommended to run a Valkey cluster with servers running on different minor versions.
Users should avoid new features until all servers in the cluster have been upgraded.

### Minor versions
Commands may also be marked as **deprecated** in minor versions.
Deprecated commands are not removed, instead a replacement command or an alternative to using the command will be defined in the same minor version.

Minor versions usually deliver maturity and extended functionality.
### Major versions

Upgrading between minor versions does not introduce any application-level
compatibility issues.
*Major* versions are released with significant functionality that may break backwards compatibility or alter key performance characteristics.
Examples of significant functionality includes altering the behavior of an existing command, removing previously deprecated commands, changing the default value of configs, and significant refactoring for performance improvements.

Minor releases may include new commands and data types that introduce
operations-related incompatibilities, including changes in data persistence
format and replication protocol.
Upgrading from a previous major version is intended to be safe, but should be approached with caution.
You should carefully read the release notes before performing a major version upgrade.
Although Major versions can introduce breaking changes, data replicated from primaries to replicas will always be sent in a backward compatible format.
You should always upgrade replicas before upgrading primaries in order to ensure data consistency.

### Major versions
The Valkey community strives to make as few backwards breaking changes as possible.
When breaking changes are required, we will also strive to provide a way to mitigate the impact without incurring downtime to your application.

Major versions introduce new capabilities and significant changes.
## Release schedule

Ideally, these don't introduce application-level compatibility issues.
The Valkey community strives to release a stable major version once a year.
Stable minor versions are created as needed in between major releases, and we aim to release at least one minor version a year.

## Release schedule
### Release candidate

A new major version is planned for release once a year.
New minor and major versions of Valkey begin by branching off the `unstable` branch as an initial release candidate branch with a name that takes the form of *`major.minor`*, example `7.2`.
The first release candidate, or rc1, is released once it can be used for development purposes and for testing the new version.
Release candidate versions will start with a patch version of "0" and will take the form *`major.minor.patch-rcN`*, example `7.2.0-rc1` followed by `7.2.0-rc2`.
At this stage, most of the new features and changes in the new version are ready for review, and the version is released for the purpose of collecting public feedback.
Subsequent release candidates are released every couple of weeks, primarily for fixing bugs and refining features based off of user input.

Generally, every major release is followed by a minor version after six months.
### Stable release

Patches are released as needed to fix high-urgency issues, or once a stable
version accumulates enough fixes to justify it.
Once development has ended and the feedback for release candidate slows down, it is ready for the final release.
At this point, the release is marked as stable and is released with "0" as its patch-level version.

For contacting the core team on sensitive matters and security issues, please
see [SECURITY.md](https://github.com/valkey-io/valkey/blob/unstable/SECURITY.md).
Patches are released as needed to fix high-urgency issues, or once a stable version accumulates enough fixes to justify it.

## Support

As a rule, older versions are not supported as we try very hard to make the
API mostly backward compatible.
The latest stable release is always fully supported and maintained.

Upgrading to newer versions is the recommended approach and is usually trivial.
The Valkey community will provide maintenance support, providing patch releases for bug fixes and all security fixes, for 3 years from when a minor version was first released.

The latest stable release is always fully supported and maintained.
The Valkey community will also provide extended security support for the latest minor version of each major version for 5 years from when a version was first released.
The minor version to be used for this extended security support will be decided once the next major version has been launched.
The Valkey community will only patch security issues we believe to be possible to exploit, which will be up to the discretion of the TSC.

Two additional versions receive maintenance only, meaning that only fixes for
critical bugs and major security issues are committed and released as patches:
For contacting the TSC on sensitive matters and security issues, please see [SECURITY.md](https://github.com/valkey-io/valkey/blob/unstable/SECURITY.md).

* The previous minor version of the latest stable release.
* The previous stable major release.

For example, consider the following hypothetical versions: 1.2, 2.0, 2.2, 3.0,
3.2.
### List of supported versions

When version 2.2 is the latest stable release, both 2.0 and 1.2 are maintained.
| Version | Initial release | Maintenance support end | Extended Security support end |
| -- | -- | -- | -- |
| 7.2 | 2024-04-16 | 2027-04-16 | 2029-04-16 |

Once version 3.0.0 replaces 2.2 as the latest stable, versions 2.0 and 2.2 are
maintained, whereas version 1.x reaches its end of life.
## Unstable tree

This process repeats with version 3.2.0, after which only versions 2.2 and 3.0
are maintained.
The development tree of Valkey is located in the `unstable` branch in the [Valkey GitHub repository](https://github.com/valkey-io/valkey).

The above are guidelines rather than rules set in stone and will not replace
common sense.
This branch is the source tree where most of the new features are under development.
`unstable` is not considered production-ready: it may contain critical bugs, incomplete features, and is potentially unstable.

However, we try hard to make sure that even the unstable branch is usable most of the time in a development environment without significant issues.
2 changes: 1 addition & 1 deletion wordlist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ race:france
race:italy
race:usa
radix
rc
rc[0-9]*
RC[0-9]+
rdb-preamble
RDB-saving
Expand Down

0 comments on commit c8644e8

Please sign in to comment.