# Current situation:

**Rancher:** default branch of the Rancher repository is: `release/2.7` which tracks all the commits targeting the v2.7.X patch releases of the repo.
Additionally, `release/2.6` is used to backport changes to land into previous minor release series (i.e v2.6.X)

**EKS/GKE/AKS operators:** deafult branch of all three Hosted Provider Operators (referred as Operators in later sections) is `main` branch and all the development is done using the same branch.
This is not ideal and makes the branch management of the repo difficult mainly due to lacking of:

- ability to backport bugfixes/CVEs' to the older patch release series
- better mapping operator versioning strategy with Rancher versioning
- clear distinction of what changes (feature / bugfix / CVE) can/can't be included in minor/patch releases
- providing a stable and backwards compatible code with specific Rancher release
- "having a sane place to go if things go wrong" when introducing breaking changes

# Proposal:

To follow the [semantic versioning](https://semver.org/) for all Operators releases as it is done by most of the upstream open source projects (kubernetes, CAPI and most of the CAPI providers).

# Release Versioning:

Operators could follow semantic versioning for their releases. Semantic versions are comprised of three fields in the form:

MAJOR.MINOR.PATCH (X.Y.Z)

- *PATCH release* SHOULD only include:
- backwards compatible bugfixes and security fixes

- *MINOR release* CAN include:
- Introduction of new API versions and field additions
- Breaking API changes for deprecated APIs, fields, or code.
- New features, but *without changing the existing behaviour*

- *MAJOR release* CAN include:
- New features, bugfixes or both which *changes the behaviour from the previous release* (not backwards compatible with previous releases).

# Branch management

Operators will have two types of branches: `main` and stable `release-X` branches.

1. The main branch is where all the developments happen and over time, it keeps diverging out of the latest stable release branch and contains all the latest and gretest code including the breaking changes.

2. Operators will maintain two stable release branches. Once Rancher releases a new `MAJOR` (v3.0.0 release cut from release/3.0 branch) or `MINOR` (v2.8.0 release cut from release/2.8 branch) release, we will create a new stable branch (release-2.0 for `MAJOR` or release-1.6 for `MINOR`) in Operators for the prior `MAJOR` or `MINOR` Rancher release and if agreed and there are no requirements for support, the oldest stable branch (release-1.4) of Operator could be dropped from the maintainance.

## CVE/Bug Fix introduced

Let's assume, latest GKE operator release is `v1.5.2` and we already created additional two stable release branches `release-1.5` & `release-1.4` in GKE operator by going back in time to the commits which are compatible with Rancher `release/2.7` & `release/2.6` branches accordingly.

In that case, the fix will be applied to both the main and two stable branches, and there is no need to create a new stable branch.

| Compatible Rancher branch | Operator Branch | Original Operator version | New Operator version |
| --------------------------| --------------- | ------------------------- | -------------------- |
| future release/2.8 | main | - | - |
| release/2.7 | release-1.5 | v1.5.0 | v1.5.1 |
| release/2.6 | release-1.4 | v1.4.3 | v1.4.4 |

## New major/minor Rancher version is out

We will create a new stable release branch (release-1.6) from *main* and the oldest stable release branch (release-1.4) could be considered as an out of support depending on Rancher matrix support (i.e. it depends if release/2.6 would be still supported when new v2.9.X Rancher is out).

| Compatible Rancher version | Branch | Original Operator version | New Operator version |
| ---------------------------| -------------| --------------------------- |--------------------- |
| future release/2.9 | main | - | - |
| release/2.8 | release-1.6 | N/A. | v1.6.0 |
| release/2.7 | release-1.5 | v1.5.1 | v1.5.2 |
| release/2.6 | release-1.4 | v1.4.4 | out of support |

# Backporting a patch

It is a best practice in the open source community to not accept PRs directly against release branches, while backports of fixes/changes already merged into the main branch are accepted.

Some guidelines for this process to follow:

1. Only critical bugs fixes, security issue fixes, or fixes for bugs without easy workarounds are candidates for stable release branches
2. Once PR is open towards main branch and meets the requirement of 1, same changes should be submitted to the both stable release branches. it should be the responsibility of the PR author to open a pull request against stable release branches, and it is the responsibility of the reviewers to help identify stable release branch-candidate pull requests.

**Note:** We generally should do not accept backports to stable release branches that are out of support.

# Release Management

## Patch releases

Patch release can be made every 3-4 weeks generally depending of course on the developement frequency.
If there is an urgent need for a fix, a patch release can be made outside of the planned schedule.

## Minor releases

Minor release frequency will be tied to the Rancher minor release cutting timelines.

## Major releases

Major release frequency will be tied to the Rancher major release cutting timelines.

# QA validation

`Supported Rancher vs Operator versions` matrix table should be provided for easier mapping and testing to the QA team. This could look like exactly the same or similar to the table provided in [New major/minor Rancher version is out](#New-major/minor-Rancher-version-is-out) section. This way, it should be easy to identify the release versions mapping of both Rancher and operators and perform a QA validations using the specific release versions of components.