🗣[Discussion] branching and release strategy

[BinaryMuse]

Currently, we target feature PRs in primer/components against the current release branch, and merging that release branch into master triggers a package publish. This particular workflow introduces a few areas of friction:

1. The release branch changes often enough that it’s difficult to know where to start a PR from. If a release branch exists, you need to find it (git branch -a | grep origin/release- or visit the GitHub UI and check the PRs). If the branch doesn’t exist because a release was recently merged, you need to cut one from master, but since the release branch needs to have the appropriate version number in its name, you need to plan ahead for which PRs you’re going to include in the branch.
2. Because the release branch changes over time, automated tools like Dependabot don't work well, since its config depends on specifying a consistent branch to target. This results in the need to manually update the base branch for each Dependabot PR (or manually update the dependencies yourself, skipping Dependabot entirely).
3. Since release branches tend to be relatively long-lived, it’s more difficult to know when issues are fixed; a feature could be “finished” but its issue would still be open for several days or more because the PR must be merged into the default branch (master) before the issue is automatically closed. [Edit: I just noticed that indirectly merging a PR into master doesn't actually close any issues tagged as being fixed by the PR, so this problem is worse than I thought]

I’d like to suggest the following change:

1. Create a new branch named develop (or similar) based off master
2. Set this new branch as the default branch on GitHub

Doing so would result in the following:

1. Since develop always contains the latest changes, any new feature branch could confidently be cut from it and merged into it without much thought (solves issue 1 above)
2. Dependabot and other automated tools have a predictable and up-to-date branch to target PRs against (solves issue 2 above)
3. All feature PRs would automatically target the develop branch by default; as soon as a feature PR is merged, its associated issue will be closed (solves issue 3 above)
4. We don't need to change any release tooling like primer/publish as master remains the branch that triggers releases

With this strategy, when we're ready to cut a release, we can cut a very short-lived release branch off develop targeting master, choosing its name and version based on the commits that will be merged. This can be merged/released as soon as we're confident that the release is solid (which should be relatively easy since it's a copy of the tip of develop).

Interested in hearing folk's thoughts! @primer/ds-core

[BinaryMuse]

(Also, in theory, release branch creation could be fully automated if PRs were labeled with the kind of semver change they'd induce)

[simurai]

merged into it without much thought

🤗 I like the "merge as soon as something feels ready".

One question: Is there a good way to find all the PRs that are on develop but not on master yet? So we can use it to write the CHANGELOG when creating a new release branch. Looking through the commit history to find the PRs is pretty tedious. I think for Atom we used some script that collected these PRs? 🤔

/cc @shawnbot Might be something for Primer CSS as well?

[BinaryMuse]

One question: Is there a good way to find all the PRs that are on develop but not on master yet? So we can use it to write the CHANGELOG when creating a new release branch.

Absolutely; in fact, if we label our PRs with appropriate semver tags, we could automate the entirety of the creation of the release branch, the PR, and the changelog.

[shawnbot]

I'm personally a huge fan of this as well, and would love to help figure out how to automate certain aspects of this workflow because it would make releasing so much easier.

I would also be down to test this out on another repo like stylelint-config-primer where there's less "risk" than in Components or CSS.

[colebemis]

in fact, if we label our PRs with appropriate semver tags, we could automate the entirety of the creation of the release branch, the PR, and the changelog.

I love the idea of automating more of the release process 😍 This plan looks good to me. We just have to make sure that we're consistent about our release workflow across all of our libraries or I can see people getting confused.

[shawnbot]

I've looked into using semantic-release via Actions before, and it sounds from semantic-release/semantic-release#974 like folks have had success with Actions v2. It would be really rad if we could preview the results of the merge (maybe the updated CHANGELOG?) before the release is published, so that we could be sure it's going to do what we expect.

[BinaryMuse]

I've looked into using semantic-release via Actions

@shawnbot We used semantic-release pretty extensively on the Electron satellite packages and it worked pretty well. Since it requires semantic commit messages, maybe it's something we could explore doing next?

---

If folks don't have any objections, I'd like to give this a shot starting tomorrow. Assuming no objections, I'll do the following tomorrow:

1. Cut a new branch from master called develop
2. Set the same protected branch rules as master on develop
3. Change the "default branch" on GitHub to develop
4. Update the base for existing PRs as appropriate

[emplums]

Correct me if I'm missing something, but the basic idea is essentially the same as having a named release branch but instead of predetermining a version number we keep that version number ambiguous until we decide to merge the branch into master?

I like the idea of having a persistent branch name that doesn't change to pull from, and think that will be helpful, but I think before we make this change we need to first put into place some of those automation features - without the automations in place I think this will make managing releases in the meantime pretty tedious for a few reasons:

• Having a release branch + tracking PR was nice because it as work got done contributors would update the description in the tracking PR - without someplace where we're collecting these updates I'd need to comb through the commits in the develop branch to determine what work has been done. That can be a little tedious to do especially since we haven't been in the practice of squashing our commits (which we could totally change)! Until we get the automation done, could we still keep an open PR for the develop branch where we can log what's been merged into it since the last merge into master?

• I'm not sure if this is what you were advocating for, but I don't think it makes sense to close issues that have been merged into the develop branch. The issue isn't really fixed until it's in a public release somewhere, and if we close them as we merge into develop we won't have a good way of knowing which issues have actually been published yet.

Couple of questions!:

If the idea is that we'd be releasing more often, I'm curious how we will know it's time to make a release branch off of develop? If we automate it - how would that work flow work? Would it automatically create a release after a certain # of PRs have been merged into the release branch or would it wait a certain number of days? For major releases, I tend to want to bunch those up and introduce some intentional wait time - the reason being I want to avoid asking consumers of the components to refactor around breaking changes as infrequently as possible. Maybe major releases would go into a separate "holding" release PR? Not sure if that even makes sense to do or if it undermines the premise of this experiment!

[BinaryMuse]

• Having a release branch + tracking PR was nice because it as work got done contributors would update the description in the tracking PR - without someplace where we're collecting these updates I'd need to comb through the commits in the develop branch to determine what work has been done.

I agree, automation around this would be nice, and I'd be happy to get this in place before we make any changes. Personally, I think the best situation is that we start using semantic PR titles/merge commit messages and just let the automation fully build the changelog. I've been on other teams at GitHub where this has worked pretty well.

• I'm not sure if this is what you were advocating for, but I don't think it makes sense to close issues that have been merged into the develop branch. The issue isn't really fixed until it's in a public release somewhere, and if we close them as we merge into develop we won't have a good way of knowing which issues have actually been published yet.

I'm not sure I personally agree with this; I guess it depends on whether you see the issue tracker as a tool for users of the package or for the developers of the package. I think of a closed issue as "this has been merged to the default branch and I don't need to think about working on it any more," while the release tracking PRs keep track of which of those are yet to be released.

Another problem is that if you have a PR that claims to fix an issue (e.g. Fixes #1) and you merge that into another branch, and then merge that branch into the default branch via another PR, the issue doesn't get closed at all, and remains open indefinitely until it is manually closed.

I'm curious how we will know it's time to make a release branch off of develop? If we automate it - how would that work flow work? Would it automatically create a release after a certain # of PRs have been merged into the release branch or would it wait a certain number of days? For major releases, I tend to want to bunch those up and introduce some intentional wait time

I guess there are a few ways to handle it; if the changes aren't dependent on each other, then the "major changes" features could be merged to the default branch and then just cherry-pick which ones we want to release into the release PR somehow. This does make the automation trickier, and sometimes people will work on a minor/patch level change that accidentally depends on the major change which breaks this workflow. We could also just leave major version changing PRs open until we're ready to prep them for release.

I've written up two or three ideas about how the automation could work, but each of them runs into issues based on the way primer/publish works (specifically, needing the PR to be from a release- branch in order to properly publish RCs to npm). I think I will need some more time to think about it, and would value any ideas or maybe a sync conversation to discuss.

[shawnbot]

I've written up two or three ideas about how the automation could work, but each of them runs into issues based on the way primer/publish works (specifically, needing the PR to be from a release- branch in order to properly publish RCs to npm). I think I will need some more time to think about it, and would value any ideas or maybe a sync conversation to discuss.

I wouldn't consider the release candidate versioning a blocker for this. We would still get canary releases, and with a new process in place we can update primer/publish to tag RC versions based on, say, output from a previous Actions step, or by running a command a la semantic-release --dry-run?

[BinaryMuse]

Yeah that's a good point. Automation could also manage the version number in package.json that primer/publish could potentially work off of. I'll work on this stuff this week/next and hopefully have something to try out soon.

[colebemis]

Closing now that we have changesets 🎉