diff --git a/RELEASE_GUIDELINES.md b/RELEASE_GUIDELINES.md index b9434db58c..c4724f6d84 100644 --- a/RELEASE_GUIDELINES.md +++ b/RELEASE_GUIDELINES.md @@ -1,4 +1,19 @@ -## RELEASE GUIDELINES +# Versioning and Release Guidelines + +This document details the versioning, release plan and release guidelines for LitmusChaos. Stability +is a top goal for this project, and we hope that this document and the processes +it entails will help to achieve that. It covers the release timelines, tracking, process, versioning +numbering, support horizons, and API stability. + +If you rely on LitmusChaos, it would be good to spend time understanding the +areas of the API that are and are not supported and how they impact your +project in the future. + +This document will be considered a living document. Scheduled releases, supported timelines, and API stability guarantees will be updated here as they +change. + +If there is something that you require or this document leaves out, please +reach out by [filing an issue](https://github.com/litmuschaos/litmus/issues). - There is a scheduled release on the 15th of every month on the following repositories: - [Litmus](https://github.com/litmuschaos/litmus) @@ -7,8 +22,6 @@ - [Chaos-Exporter](https://github.com/litmuschaos/chaos-exporter) - [Chaos-Charts](https://github.com/litmuschaos/chaos-charts) -- Repositories use release version according to the [Semantic Versioning](https://semver.org/) - - Docker images with release tags are pushed upon creation of a github release - Following are the docker images: @@ -32,6 +45,157 @@ - Doc sanity tests - Litmus release with change log +## Releases + +Releases of LitmusChaos will be versioned using dotted triples, similar to +[Semantic Version](http://semver.org/). For the purposes of this document, we +will refer to the respective components of this triple as +`..`. The version number may have additional information, +such as alpha, beta and release candidate qualifications. Such releases will be +considered "pre-releases". + +### Major and Minor Releases + +Major and minor releases of LitmusChaos will be made from main. Releases of +LitmusChaos will be marked with GPG signed tags and announced at +https://github.com/LitmusChaos/LitmusChaos/releases. The tag will be of the +format `v..` and should be made with the command `git tag +-s v..`. + +After a minor release, a branch will be created, with the format +`release/.` from the minor tag. All further patch releases will +be done from that branch. For example, once we release `v1.0.0`, a branch +`release/1.0` will be created from that tag. All future patch releases will be +done against that branch. + +### Pre-releases + +Pre-releases, such as alphas, betas and release candidates will be conducted +from their source branch. For major and minor releases, these releases will be +done from main. For patch releases, these pre-releases should be done within +the corresponding release branch. + +While pre-releases are done to assist in the stabilization process, no +guarantees are provided. + +### Upgrade Path + +The upgrade path for LitmusChaos is such that the 0.0.x patch releases are +always backward compatible with its major and minor version. Minor (0.x.0) +version will always be compatible with the previous minor release. i.e. 1.2.0 +is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0. There is +no compatibility guarantees for upgrades that span multiple, _minor_ releases. +For example, 1.0.0 to 1.2.0 is not supported. One should first upgrade to 1.1, +then 1.2. + +There are no compatibility guarantees with upgrades to _major_ versions. For +example, upgrading from 1.0.0 to 2.0.0 may require resources to migrated or +integrations to change. Each major version will be supported for at least 1 +year with bug fixes and security patches. + +### Next Release + +The activity for the next release will be tracked in the +[project board](https://github.com/litmuschaos/litmus/projects). If your +issue or PR is not present in the project board, please reach out to the maintainers or discuss the same on the #litmus-dev slack channel to create the milestone or add an issue or PR to an existing milestone. + +### Support Horizon + +Support horizons will be defined corresponding to a release branch, identified +by `.`. Release branches will be in one of several states: + +- __*Next*__: The next planned release branch. +- __*Active*__: The release is a stable branch which is currently supported and accepting patches. +- __*Extended*__: The release branch is only accepting security patches. +- __*LTS*__: The release is a long term stable branch which is currently supported and accepting patches. +- __*End of Life*__: The release branch is no longer supported and no new patches will be accepted. + +Releases will be supported at least one year after a _minor_ release. This means that +we will accept bug reports and backports to release branches until the end of +life date. If no new _minor_ release has been made, that release will be +considered supported until 6 months after the next _minor_ is released or one year, +whichever is longer. Additionally, releases may have an extended security support +period after the end of the active period to accept security backports. This +timeframe will be decided by maintainers before the end of the active status. + +Long term stable (_LTS_) releases will be supported for at least three years after +their initial _minor_ release. These branches will accept bug reports and +backports until the end of life date. They may also accept a wider range of +patches than non-_LTS_ releases to support the longer term maintainability of the +branch, including library dependency, toolchain (including Go) and other version updates +which are needed to ensure each release is built with fully supported dependencies and +remains usable by LitmusChaos clients. _LTS_ releases can also accept feature backports +to support new Kubernetes releases. The default action has to be reject it though, +for long-term stability. This is still negotiable when the feature is a hard dependency +for a new release of Kubernetes. There should be at least a 6-month overlap between +the end of life of an _LTS_ release and the initial release of a new _LTS_ release. +Up to 6 months before the announced end of life of an _LTS_ branch, the branch may +convert to a regular _Active_ release with stricter backport criteria. + +The current state is available in the following tables: + +| Release | Status | Start | End of Life | +| --------- | ------------- | ------------------ | ------------------- | +| [0.x {0.6 - 0.9}](https://github.com/litmuschaos/litmus/releases/tag/0.9.0) | End of Life | Sept 13, 2019 | Jun 15, 2020 | +| [1.x {1.0 - 1.13}](https://github.com/litmuschaos/litmus/releases/tag/1.13.8) | End of Life | Jan 8, 2020 | - | +| [2.0 beta {2.0 beta 0 to 2.0 beta 9}](https://github.com/litmuschaos/litmus/releases/tag/2.0.0-Beta9) | End of Life | Mar 05, 2021 | July 15, 2021 | +| [2.x](https://github.com/litmuschaos/litmus/releases/tag/2.14.0) | End of Life | Aug 9, 2021 | September 5, 2023 | +| [3.x beta](https://github.com/litmuschaos/litmus/releases/tag/3.0.0-beta12) | End of Life | Nov 16, 2022 | Nov 15, 2023 | +| [3.x](https://github.com/litmuschaos/litmus/releases/tag/3.6.1) | Active | Oct 04, 2023 | active(release of 4.0 + 6 months), | +| [4.0](https://github.com/litmuschaos/litmus/blob/master/ROADMAP.md) | Next | TBD | TBD | + +> **_NOTE_** LitmusChaos v3.x will end of life at the same time as v4.x reaches full stability. Due to +> [Minimal Version Selection](https://go.dev/ref/mod#minimal-version-selection) used +> by Go modules, 3.x must be supported until EOL of all 3.x releases. Once 3.x is in +> extended support, it will continue to accept security patches in addition to client +> changes relevant for package importers. + +### Kubernetes Support + +The Kubernetes version matrix represents the versions of LitmusChaos which are +recommended for a Kubernetes release. Any actively supported version of +LitmusChaos may receive patches to fix bugs encountered in any version of +Kubernetes, however, our recommendation is based on which versions have been +the most thoroughly tested. See the [Kubernetes test grid](https://testgrid.k8s.io/sig-node-LitmusChaos) +for the list of actively tested versions. Kubernetes only supports n-3 minor +release versions and LitmusChaos will ensure there is always a supported version +of LitmusChaos for every supported version of Kubernetes. + +| Kubernetes Version | LitmusChaos Version | +|--------------------|-------------------------------| +| 1.26 | 1.x, 2.x | +| 1.27 | 1.x, 2.x | +| 1.28 | 2.x, 3.x | +| 1.29 | 3.x | +| 1.30(wip) | 4.0 (wip), 3.x | + + +## Public API Stability + +The following table provides an overview of the components covered by +LitmusChaos versions: + + +| Component | Status | Stabilized Version | Links | +|------------------|----------|--------------------|---------------| +| GraphQL API | Stable | 1.0 | [graphql API]() | +| Go client API | Stable | 2.0 | [godoc]() | + + +From the version stated in the above table, that component must adhere to the +stability constraints expected in release versions. + +Unless explicitly stated here, components that are called out as unstable or +not covered may change in a future minor version. Breaking changes to +"unstable" components will be avoided in patch versions. + +Go client API stability includes the `client`, `defaults` and `version` package +as well as all packages under `pkg`, `core`, `api` and `protobuf`. +All packages under `cmd`, `contrib`, `integration`, and `internal` are not +considered part of the stable client API. + + + ### Release Checklist * [ ] Release branch creation on litmus component repos