Branch management

[rootulp]

Context

Currently celestia-app maintains two branches:

1. main
2. v1.x

Most PRs target main by default and are optionally backported to v1.x if they need to be included in a subsequent v1.x release.

Problem

The backport process leads to friction because it leads to two PRs for most changes. The added friction has caused fixes to be merged to main without being merged to v1.x (example).

Proposal

My hunch is that the number of changes on main that need to be released in v2.0.0 are extremely small compared to the number of changes on main that can be released in a subsequent v1.x release. I think the maintenance burden originates from us prematurely creating and maintaining a v1.x branch. My proposed branch management:

• main is the default branch that PRs target. The latest releases are always cut from main.
• Create a longer-lived v2.x branch for breaking changes. This branch should have branch protection rules and shouldn't merge to main until immediately prior to us creating v2.0.0. At that time, we can create a longer-lived v1.x branch that only accepts critical fixes that need to be backported.

Steps

1. Cherry pick all the breaking changes on main that need to be released in v2.0.0 to a new branch v2.x.
2. Revert all the breaking changes on main.
3. Deprecate the v1.x branch.
4. Cut subsequent v1.x releases from main.

Optionally:

1. Open up a draft PR of v2.x that targets main.
2. Add branch protection rules on v2.x.

When we eventually cut a v2.0.0, we may create a v1.x branch that accepts backports and doesn't include the v2.x breaking changes. At that point, main will be the default branch for all PRs because most changes should target subsequent v2.x releases and only critical fixes need to be backported to v1.x.

Notes

If we plan on cutting a v2.0.0 in the short-term, this proposal doesn't provide much benefit. But the idea may still apply to future releases. For example, we can delay the creation of a v3.x branch until the time where main introduces v3.x breaking changes.

[cmwaters]

I'm a little confused here. If I understand correctly you want to make it that we cut minor releases from main and instead put breaking changes into a v2.x branch which will get merged into main prior to cutting v2.0.0.

[rootulp]

yep exactly. After the point where we cut a v2.0.0, we can no longer cut v1.x releases from main b/c main will contain breaking changes that are incompatible with v1.x so we must create a v1.x release branch at that time that only accepts backports (likely just fixes).

The idea is to delay the moment at which we create a release branch for the previous release until the time we cut the next major release. This way we can continue to develop and release non-breaking changes from the main branch.

[MSevey]

I'm in favor of the default being we always cut releases from main.

The version branches are primarily beneficial for actually backporting, i.e. v1.3.1 branch for back porting fixes for v1.3.1 while the next version is in process. The process of maintaining a v1.x release branch isn't backporting, it is maintaining an entirely separate stable branch.

One thing to consider, is building the practice of never implementing a change in a breaking way until the version is ready to released. When dealing with breaking changes, there is going to be some maintenance burden on the team to manage the breaking change until the version is release. You can either do this by putting that change in a separate branch, or you can do it by taking on some short term tech debt of maintaining separate workflows in the code.

imo maintaining separate workflows in one branch is easier than maintaining 2 branches.