Move to a single branch release flow on "main" branch

[suzubara]

As @haworku and @eamahanna witnessed, our current release flow is flawed:

• Merging the release branch into master requires that we also have to keep develop up-to-date with the release branch changes. This means an extra PR that must be approved
• Since we've transitioned to using squash & merge on this repo exclusively, the workflow of develop -> release branch -> master -> develop breaks with a linear commit history, and also results in a loss of commit history since release PRs are squashed on master

My suggestion is the following:

• Deprecate the current master branch and use only one main branch for active development and stable versions (naming can be TBD)
• Stable versions will always be accessible via their associated tag.
  • Version tags should be checked out if the code at a specified version needs to be examined, or when making maintenance fixes.
• The new release flow will be: main branch -> create release branch, update version/changelog -> approve release branch PR -> merge release into main branch -> tag and publish

Pros:

• Removes extra step of merge into master and also into develop
• Removes potential confusion of which branch a release PR should be based off
• Keeps a cleaner commit history using squash & merge (the release branch merges will always just reflect the chore: release commit, which should always only be the new version number and changelog updates)
• Release hotfixes should be made directly off of develop (and merged back into it)

Cons:

• From the time of creating the release branch, all other merges to develop should be prevented until the release has been completed. Otherwise we risk publishing a release that has unaccounted-for changes.
  • Mitigation: I would argue that right now, this project is small enough that we can mitigate that from happening with good team communication. Release PRs should take priority over any other PR reviews, and anyone issuing a new release can communicate via Slack that no PRs should be merged until it's completed.
  • Mitigation: if new work does get merged in while a release PR is open, it can be resolved by requiring release-* branches always require being up to date with their base branch before being merged (this is a Github branch protection setting)

[eamahanna]

I think this makes sense given it reduces the overall complexity with releases. I would just want to make sure the release documentation reflects that you need to make a PSA to the react-uswds channel when doing a release (just to make sure this doesn't get overlooked).

[duncan-truss]

I've seen a git workflow where we'd merge the release branch back into develop instead of closing it and merging master back into develop. Would that simplify anything?

[suzubara]

@duncan-truss yes that was my suggestion

[duncan-truss]

Ok sorry I meant still keep master around because then you could still merge code to develop (won't dependbot automerge?) and choose not to add it to the release branch. I guess I proposed just instead of merging from master back to develop, make the merge from the release branch back to develop as well as master.

[suzubara]

@duncan-truss ohh I see, so open 2 PRs for the release branch (one into master and one into develop)? I don't love that the release process still involves approving/merging 2 PRs but that is less of a change than what I was proposing.. I need to do a new release anyways so I'm down to try it and will report back.

[haworku]

Hey! Open to try the single branch flow. Never tried it before.

I read this article to think more about how this would work. Also the article has a suggestion on how to keep both master and develop going while only using one main branch for any and all PRs (develop) which is what @suzubara is proposing. See the "Variation – develop + master" section.

[DanielMiller-agile6]

Just a suggestion, but here is another branching strategy I've used in the past that has worked pretty well and helped simplify things on a few projects. I haven't used it for a component library before, but might be worth considering:
http://releaseflow.org/

[haworku]

We have decided to move towards a single branch.

The new release flow will be: main branch -> create release branch, update version/changelog with yarn release -> approve release branch PR -> merge release into main branch -> tag and publish

The new process will begin with release 1.7.0.

Requirements to close this ticket:

• Create a new branch main based on master. This is the default GH branch
• Successfully release 1.7.0 from main
• Remove develop and master branches
• Double check ci and docs for references for develop/master
• Update docs with new release flow. We may want to cite some of the FAQs here.