PROPOSAL: Make releases/v4 the default branch

[plocket]

PROPOSAL: Make releases/v4 the default branch

Why?

Pros:

• I think some folks on the team would prefer this.
• Merging PRs would close issues automatically, making maintenance easier, though closing issues automatically on merge from any branch is probably a script we can/should write.
• Cloning to a local repo would start people off on the right branch.
• We're planning to focus mostly on v4 now and leave v3 behind as quickly as possible.
• It's confusing right now to see a very stale branch (main) when you land on the repo that still has code that looks somewhat relevant. I'm not sure this alternative will be less confusing considering we're still supporting v3.

Cons:

• We do need a consistent plan for what to do when we're supporting multiple stable releases. Is the default the stable release? Or is it the latest code? A stale branch made explicitly for documenting the status of the releases and links to their docs?
• When we have multiple stable versions, it's confusing to land on the main repo page and see a version that's active, but doesn't match up with what you're doing.
• Maybe this is an intellectual fallacy on my part, but I think in that situation it's not ideal to have a README of an actively supported release that links to another release version branch. Harder to maintain/clean up and a bit more confusing. Maybe we could have a stable default branch that looks significantly different that handles showing status and has up-to-date links to more information (like main does now)?
• [Merging PRs would not automatically close issues without more work from us. But, in response:] Closing issues automatically on merge from any branch is probably a script we can write, so that shouldn't be the main reason to avoid switching.

Useful resources

If someone has time to look up resources on how other projects have handled their default branches with multiple stable releases, I'd be eternally grateful.

What this looks like

• Someone with branch access edits the releases/v4 branch to be the default branch
• We delete main

Proposal history

• 04/11/2022
  • Proposal made and announced in Slack

[BryceStevenWilley]

I don't have many examples I can point to (most of my experience with this was at my last job, and those repos are private / proprietary), but my knowledge is as such:

• there is only ever 1 active branch that is being developed on and merged into, main. cucumber itself seems to do this, post version 5.
  • it always follows the current latest version. If we release v5, we wouldn't make a v5 branch, we would just keep doing things on main (see below on what it means to release a version)
  • There are sometimes, in the cases of large refactors, separate branches for older stable versions, but that's rare / only for when you can't generally cherry pick changes around. IMO, it's more work, and for a smaller project like ourselves (1 primary maintainer, 1-2 consistent contributors at any given time), we should avoid making that maintenance burden.
• work on features that we want to backport to earlier releases and bug fixes that apply to older releases are still always targeted at main, and then cherry-picked and adapted to the older releases. You can keep the main PR open and make PRs targeting the older releases (see below for how those branches should live), merging them at the same time.
• each stable version has a tagged release, i.e. version 3 would have a tag for 3.2.1
• Once you release a stable version, you don't need a permanent branch for it, just the latest tag
  • this works because in git, tags are the same internal object as a branch. You can easily make a branch that starts at an existing tag.
  • this also works because most work on older versions should be patches and bug fixes only. We can take those as they come, creating a new branch for the next stable release from the latest stable tag, merging bug fix PRs or cherry-picking commits from main onto that branch, and then making a new release/tag from the branch, removing it later.
  • removing the branch makes sure that the branch and the releases don't get out of sync. We know that it if there's a releases/v3.2 branch, it still needs to be released.

[plocket]

I'm not sure about implementing that exact model, but it does give me some thoughts about consistent rules we could set up for this kind of situation. I'll try to make another proposal soon for that broader issue.

[BryceStevenWilley]

To specifically refute some of the other cons:

it's confusing to land on the main repo page and see a version that's active, but doesn't match up with what you're doing
I agree. Github isn't super great at navigating you to the same branch that you are looking at, and I always end up accidentally using the navigation tabs and ending up at the default branch anyway. This is bad for both sides of making default latest and making it stable, IMO: someone might be on 3.1 still, but github will consistently take them to 3.2.1, etc. I think the expectation of developers is that github shows the latest information. We don't have our own documentation site, just a page on a different site, but that's where this could be addressed, something like python's documentation site, with the version selector at the top.

it's not ideal to have a README of an actively supported release that links to another release version branch. Harder to maintain/clean up and a bit more confusing

Agreed as well, but the fix IMO is to just link to the github tags / releases page saying "This is version 4.x.y. If you are looking for another version, check here", and not link to specific versions from the README.

Closing issues automatically on merge from any branch is probably a script we can write, so that shouldn't be the main reason to avoid switching

Really don't think we should make more debt to do that task, even if it's possible to achieve.

[plocket]

link to the github tags / releases page

I'm not convinced about tagged releases yet, but we can talk about that more [in another proposal].

make more debt to do that task

Tech debt is a good point. I'd thought of it as something to do and forget, but how often is that really the case. 👍