DECISION: No main branch, but bleeding edge branch will be made the default branch

[plocket]

DECISION:

See outlined solution lower down for more on rationale.

Summary:

• no main branch! The default branch of the GitHub repo will always be the newest "N" of releases/vN.
  • changing a default GitHub branch is low friction and doesn't have many knock-off effects
  • making the default GitHub branch the target for development makes onboarding users new to GitHub easy, and gets rid of some small annoyances for seasoned contributors
• all stable versions that we still support will still exist as branches: releases/vM, where M < N (i.e. v2 < v4)

---

---

Rejected:

PROPOSAL: main will be the latest stable release of the latest stable major version

Basically, what npm would call latest.

Why

We need a reliable and replicable way to manage multiple stable releases if/when new versions are on the horizon.

What this looks like

• A maximum of two major releases would be supported, and only if absolutely needed.
• The latest stable release the latest stable major version would be on main and be the default branch.
• It would be maintained with new necessary features and bug fixes.
• Any new major version that wasn't ready for release would be created on a new branch called releases/vN, where N is the next major number.
• Any older, previously supported, releases would be retired and their branches deleted.
• Each version will keep its own README up to date. Ideally, there would be no differences needed.
• If different READMEs are needed, main will point to the READMEs of the other version.
• Once the newest version is officially released for use, it becomes main and we retire and delete the old branch as soon as it's feasible.

Our historic needs

These were our needs for v4.

1. Maintain many minor updates of new features to the current stable/supported release (v3), as well as bug fixes. These new feature updates were requested by users while v4 was taking over a month to be released for use.
2. Keep the new unstable release/code up to date with those changes.
3. Keep the newest code out of circulation as it was not ready to be used.
4. Keep developing actively on the new code.

Prior Discussion

This comment from @BryceStevenWilley suggests a slightly different variation. Including it here for full context:

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.

I appreciate that this worked for a prior project. I think other than tags, it lines up a lot with what I'm proposing.

As far as tags go, I personally haven't worked with them before, so maybe there are things I'm not seeing. I also haven't run into many people who have (or who have discussed it), but that might not be as relevant. The level of activity that needed to happen with maintaining v3 doesn't match up with what the above describes. Juggling back and forth between branches and tags sounds like it would have been too much work in the situation we were dealing with. It could potentially add a flag that something needs to be released, but that can go wrong just like everything else us humans do.

Proposal history

• 04/30/2022
  • Proposal made
• 08/10/2022
  • New proposal made
  • Votes: two members give 5
  • Decision was implemented

[BryceStevenWilley]

My suggestions to this proposal:

• main should be the latest version, not the latest stable version
  • the latest version will get new features and bug fixes
  • stable versions should only get bug fixes, and occasionally (less often than latest), new features.
• all stable versions that we still support exist as branches: releases/vN

The process looks like:

• the tip of main is always considered "bleeding edge", and might contain bugs (as all active development does)
• At any point, if we decide that the code is ready for consumption, we make the version (e.g. v5.2) we can note the commit (can be with a tag, but this is optional), and release it to npm. The npm release is the point of consumption for most users.
• If we decide to make a breaking change, we then make the new version branch from main, (releases/v5), commit our breaking changes to main, bump the version on main, and continue development.
  • now main is bleeding edge. But it's not "visible" to end users until we make a new major version on npm (v6.0).

This will simplify a few things:

• all new features and code go into main. If we want to backport a new feature to an existing release, we can do so with git cherry-pick <commit-hash> <additional-commit-hash> ...
• when we want to make a breaking change (i.e. a new major version), all we need to do is make a new branch. Work specific to the release (like extra documentation, changing readme, etc.) can be done is just that branch
• notably, all merges are in one direction: from main to other branches. Using the other process complicates things, as merges can now happen from already released branches back on the new version in development, slowing down development.

This also should address our historic needs:

Maintain many minor updates of new features to the current stable/supported release (v3), as well as bug fixes. These new feature updates were requested by users while v4 was taking over a month to be released for use.

This is still possible with the proposed process: v4 would have lived on main while in development, and we could independently patch releases/v3.

Keep the new unstable release/code up to date with those changes.

This is now done by default, without any extra work, as everything is on main.

Keep the newest code out of circulation as it was not ready to be used.

Code is always out of circulation until we make an npm release.

Keep developing actively on the new code.

This is optimized for, as development is always on one branch: main.

Agreed that we can do without tags. We might be able to use them in a lighter manner, simply marking npm released versions on main, so visitors to the Github can easily jump to their version of the code.

[plocket]

I'm coming along for the ride, but have some questions.

when we want to make a breaking change (i.e. a new major version), all we need to do is make a new branch

The above implies that main is not the bleeding edge version. The new branch is the bleeding edge version, but it's not the main branch.

Code is always out of circulation until we make an npm release.

What about when we need to try out a change in the wild? We'll need to release to npm.

I'm not sure I agree with everything above - some of the flows above just seem like mirror images from flows that are just as simple - but I'm not going to die on this hill. I just want to understand the proposed procedure a bit better.

[BryceStevenWilley]

The above implies that main is not the bleeding edge version. The new branch is the bleeding edge version, but it's not the main branch

The example in the paragraph above it (copied below) describes the actual process. The new branch is specifically for the release, not main. I was trying to edit that sentence down and did so too much.

"If we decide to make a breaking change, we then make the new version branch from main, (releases/v5), commit our breaking changes to main, bump the version on main, and continue development"

What about when we need to try out a change in the wild? We'll need to release to npm.

We can still do that, by just making a beta release: @suffolklitlab/alkiln@5.0.0-beta1. Don't tag it as latest, and it'll be fine.
In general I think we should try to minimize the time [effort] between deciding that we're making a breaking change (and splitting main off into a new release branch), and actually releasing that breaking change as a new major version. As mentioned previously, if that process was to make a new unreleased releases/v5 branch, while continuing to work on main as the stable version, you have to do a lot of merging into the active development branch, which is harder and will slow down development. Given the limited amount of developers we have on the project, I think we should try to minimize development time.

Also notable right now is that the action.yml is pulled from GitHub. With the suggested process in this discussion (and our current process), anytime we move main to a new stable version, we'll be updating it to a new version with possible breaking changes to the action.yml. With this process, by checking out your action from main, you're opting in to possible breaking changes. If you want a stable release (as most people will), you can checkout a specific releases branch.

I'm not sure I agree with everything above - some of the flows above just seem like mirror images from flows that are just as simple

You're right that they're mirror images, IMO

1. the process is just as simple, but the merge conflicts that they'll create trying to share code (and updating main) aren't, and I think my proposal will be simpler to maintain multiple parallel supported versions.
2. I'm explicitly trying to bias towards development speed and simplicity, as opposed to prioritizing support of older versions. We should still support them, but I don't think they should be the priority once there's a new major version.

https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-tags-for-release-management

To be clear, if you aren't convinced, we shouldn't do it. You're the lead maintainer, and I don't want to add processes to the project that you don't agree with. We can hop on a call to discuss more if you want.

[plocket]

A call might be useful - this answers some questions, but brings up more questions.

[BryceStevenWilley]

Had a longer conversation about this, and we landed on the fact that main still changes for users means they won't want to use it and will stay on too-old releases without the newest still stable commits. The crux between this proposal and the proposal above is that something has to change, either developers finding which branch is the default, or users not wanting things to change. I'm going to write out a (hopefully shorter) proposal that we both agreed is the best option going forward in a different comment.

[BryceStevenWilley]

My final proposal (as we brainstormed on a call):

• no main branch! The default branch of the GitHub repo will always be the newest "N" of releases/vN.
  • changing a default GitHub branch is low friction and doesn't have many knock-off effects
  • making the default GitHub branch the target for development makes onboarding users new to GitHub easy, and gets rid of some small annoyances for seasoned contributors
• all stable versions that we still support will still exist as branches: releases/vM, where M < N (i.e. v2 < v4)

If we want to:

• make a breaking change, we would simply make a new release branch (i.e. releases/v5) from the latest development branch (releases/v4), and change the default GitHub branch to releases/v5. Work continues on releases/v5 until we're ready to release, then we publish the code to npm as a new major version.
• make a minor or patch releases, we simply update the package.json version number in the right branch, update the changelog, and npm publish that branch
  • if the branch is not the latest branch, we can do npm publish --tag stable, which won't update the latest tag on npm
  • this process could eventually be done by a GitHub workflow to simplify things
• apply a fix from one release to another, we can cherry-pick commits to avoid messy merges between released branches. The cherry picks can go in either direction, whichever is easier for the fix.

Users of the action.yml can use either branches or GitHub tags: SuffolkLITLab/ALKiln@releases/v4 can be used if they want the latest action.yml (which might have non-breaking quality-of-life improvements to the action, but won't change required environment variables / action parameters), or they can use SuffolkLITLab/ALKiln@v4.3.2 if they prefer stability.

• note that GitHub tags can be force-pushed and overriden, so if users want true security in don't trust us as stewards of the repo, they should copy the entire action.yml into their own repository, which we (or a presumably malicious hacker) would not have access to..