What/Why

What are you proposing?

We should change the branching strategy used across the OpenSearch Project to track two releases instead of three. We should make this change when we do the next major version release (3.0) of the distribution.

This change applies to all repositories that are part of the OpenSearch distribution (core, dashboards, plugins, etc). Some repositories, such as clients, have independent release cycles and are not impacted by this change.

Background

Currently, we track three releases in parallel:

• 3.0 (the next major release) on the main branch
• 2.x (the next minor release) on the 2.x branch
• 1.3.x (the next maintenance release) on the 1.3 branch

This strategy optimizes for being able to incubate and develop breaking changes for the next major release for an extended period of time, as that code would be on the main development branch. The cost of this strategy is that all non-breaking changes intended for the next minor release require an extra step of backporting to the 2.x branch. The previous 2.5+ years have shown us that we have incubated very few breaking changes on the main branch for an extended period. While we have automation that makes backports to the 2.x branch very low effort for the majority of changes, it is not perfect (e.g. automation hits conflicts requiring manual resolution, flaky tests may fail, it takes time even when everything works perfectly). I believe the cost of these paper cuts, multiplied by thousands of changes across scores of repos, outweigh the benefits of the current approach. I also have no reason to believe things would be different for the 3.x→4.0 cycle than it was for the 2.x→3.0 cycle.

Proposal

The proposal is to track only two releases in parallel. After the 3.0 release, we will have the following branches:

• main tracking the 3.x version (the next minor release)
• 2.<last> tracking the next maintenance release of the 2.<last> version

At the time of a minor release, we will cut a release branch (e.g. 3.1) from the main branch. Development for the following minor release will continue on main and the 3.1 version will be built from the 3.1 branch.

At the time of a maintenance release, we will create a release tag (e.g. 2.19.1) from the HEAD of the 2.19 branch. The maintenance release will then be built from the 2.19.1 tag.

What users have asked for this feature?

This is a change to development and will not impact users. Developers frequently complain about friction introduced by backports.

What problems are you trying to solve?

This proposal is an attempt to reduce development friction by optimizing for what we routinely do (develop new features in a backward compatible way targeted toward the next minor release) at the expense of what we do not do (incubate breaking changes for an extended period in a snapshot build of the next major release).

What is the developer experience going to be?

The vast majority of code changes are intended to be released in the next minor version. With this proposal, such changes will require only one PR to commit the change to the main branch. This is in contrast to the procedure today, which requires committing the change to main and triggering a backport to the 2.x branch.

Are there any security considerations?

No.

Are there any breaking changes to the API

No.

Why should it be built? Any reason not to?

We should do this to improve the developer experience across dozens of repos.

The downside is that we will have no dedicated place to stage future 4.0 changes or routinely build 4.0 snapshot distributions. If someone wants to incubate a breaking change they would need to create a separate branch and regularly rebase it against main. We would have no automated mechanism to build a complete 4.0 distribution containing breaking changes in multiple components.

What will it take to execute?

This is a change in branching convention that will have to be coordinated across all repos that are part of the distribution. Some release tooling in opensearch-build may need to be updated to handle the new convention.