RFC: Figuring out how to smooth out the autorelease pipeline

[ernestoresende]

@sammoore @danstepanov Centralizing this under a discussion because, depending on the ramifications, this could span across several issues and/or PR's.

---

I think we're getting some things mixed in terms of what part of the flow is responsible for what, so first of all, let me make sure we're all working in the same page:

This is our current situation:

beta is the default branch. main is the release branch (the one that will release new versions under the latest tag on NPM, the default).

There are GitHub Actions that run on push triggers on both beta and main:

• Pushes to beta, regardless if by a PR, or commit, will:
  • Read from existing changesets to decide if a new beta release is needed.
  • If they are needed, they publish a new release with the beta tag on NPM.
  • No changesets are consumed (they are kept there so the regular release action can do it's thing).
  • The package version isn't bumped (they are bumped during the CI run, but that change is ephemeral and dies along with the CI).
• Pushes to main, regardless if by PR or commit, will:
  • Read from existing changesets to decide if a new latest release is needed.
  • If they are needed, automatically opens a PR with a release plan and the changes accumulated so far. The PR is opened in a new branch against main.
  • That PR does not need to be immediately merged. It will keep collecting further changes until it's manually merged by someone with the permission to do so.
  • Upon merge, the same action will run again. The internals of the @changeset/action are smart enough to figure out that the merge was from a PR created by itself, and determine that, this time, it's time to publish the package.
  • The changes are live on NPM, changesets on main are cleaned, and the version is bumped accordingly on package.json. A new release cycle begins. This is where merging back to beta is highly recommended, as it will cleanup stale changesets.

What has been proposed to improve this:

Recent conversations around the topic of autorelease here seems to circle around two aspects:

1. Minimize confusion from outside collaborators regarding branch names.
2. Reduce friction by automating part of the changeset process.

"We should rename the branches something that makes more sense"

I agree. From the outside contributor's perspective, having beta as the main branch is extremely confusing. @sammoore has came up with going back to main as the default branch, and release for the locked branch where releases happen.

"We should automate the creation of changesets"

We could. I personally don't see the value. The addition of a changeset is the declaration of an intent to add/change the module behavior. Any attempt to automate that will involve fairly complicated CI and/or Git hooks shenanigans, and, most importantly, destroy the historical reference to the original commit that issued the changes.

As I've stated before, I believe the correct course of action here is making sure that:

• Everything the contributor needs to do is very explicitly delineated in CONTRIBUTING.md and pull request templates.
• That the tooling works. Much more frustrating than having to briefly learn how to handle changesets, is having the tooling fail while doing so. It's on our best interests to throughly make sure that every bit of tooling that makes this happen works.

"Merging the release branch back into the default branch breaks linear commit history"

While I do agree, I don't see a way around it that doesn't involve introducing even more complexity to the current workflow. The fact is that stale changesets needs to be cleaned out of the default branch after a release. I'm open to other ideas on how to make that happen.

[sammoore]

"Merging the release branch back into the default branch breaks linear commit history"

While I do agree, I don't see a way around it that doesn't involve introducing even more complexity to the current workflow. The fact is that stale changesets needs to be cleaned out of the default branch after a release. I'm open to other ideas on how to make that happen.

This seems to be a non-issue (!!) because fast-forward merges happen (meaning the two branches end up being at literally the same commit), since they share the same commits/base, which I think will stay true as long as we merge the chore(release): version packages consistently back into the base branch (whichever it is) before accepting another PR, and do a fast-forward merge whenever doing so.

[sammoore]

"We should automate the creation of changesets"

We could. I personally don't see the value. The addition of a changeset is the declaration of an intent to add/change the module behavior. Any attempt to automate that will involve fairly complicated CI and/or Git hooks shenanigans, and, most importantly, destroy the historical reference to the original commit that issued the changes.

[...]

I disagree with your premise here that there's no value in automating changesets. Some people will end up not reading the CONTRIBUTING document. I think it's best if we make the process as seamless as possible, so that even if people didn't read that document, they likely ended up doing everything right anyway, in order to reduce maintenance burden as much as possible.

Obviously at the current popularity of this repo, it's not a big deal, but at the end of the day our goal with this tooling is to make maintainer's lives easier, and if it's a common trope for people to not read the CONTRIBUTING document (which it already appears to be, even at this volume), we should account for that in our tooling.

I don't really see Git Hooks as "shenanigans" either. I'm happy to write a hook that asks the user if the commit they are making is a change to the CLI, and ask for a patch note if they say yes. If that saves us from asking for bunx changeset runs in just a handful of PRs, I think it will be worth it.

(I do see your point in how "the tooling should work" vs. "git hooks shenanigans", but I'm sure we can get this right so it does work on commit)

[frankcalise]

I don't think they need to be autogenerated, most large projects I contribute don't do that. But we could have a CI step to alert the contributor that it's missing in the case that it is needed. Thoughts on that?

[ernestoresende]

Good middle ground here. I have opinions on Git Hooks, but I won't let that get in the way if someone can implement it. I think my main gripe with it is the fact that, depending on the Git tooling used by the contributor, they can just be... ignored.

But I'm with Frank here. I haven't personally seen a single project using changesets that does automation on the changeset generation itself, and I don't personally think that is the way to go. I'm okay with the Git Hook asking for the changeset tho.

[frankcalise]

I was more thinking on CI, but actually mentions it's not recommended for some reason. But they also mention there is a bot to do the exact thing: https://github.com/apps/changeset-bot 🤷

https://github.com/changesets/changesets/blob/main/docs/checking-for-changesets.md

[danstepanov]

I literally lol'd

[sammoore]

"We should rename the branches something that makes more sense"

I agree. From the outside contributor's perspective, having beta as the main branch is extremely confusing. @sammoore has came up with going back to main as the default branch, and release for the locked branch where releases happen.

I've also kind of just threw my hands up and said "develop and main are fine too", given that it seems common for everyone around here, and I just want the branch names to be intuitive. In other words, I just really don't want to keep beta as a branch name.

I do think one is marginally better, but the real nit I have is with the beta branch name.

[ernestoresende]

Yeah, beta was a horrible name for this purpose, and I deeply regret having been the one to introduce it here.

[sammoore]

Totally understand your original reasoning -- it triggers beta builds -- but yeah, hindsight is 20/20!

[danstepanov]

Branch names

• beta -> new main
• old main -> release

Changesets

• We will not automate the changsests. However, we will have a check on either CI or as a pre commit hook that ensures that the changeset is provided before the PR can be merged (and that clearly indicates this to the contributor)

Merging the release branch back into the defualt branch

• No changes will be made here. Continue to rebase changes from the release branch back into the default branch after a release is completed.

[ernestoresende]

For the historical purpose of highlighting what was decided, we went back to following the regular Git flow, and abandon branching strategies for pre-releases altogether.

As @sammoore pointed out during our conversation, and being something that I massively overlooked, because pushes to the main branch do not immediately trigger a new release, there is no need for a separate branch to be responsible for triggering pre-releases:

• latest releases will happen when Changeset PR is merged by a maintainer; The PR can accumulate changes over time and not be merged just as it opens.
• next releases will happen every time a new push hits main containing one or more changesets.

It was decided that this flow led to a more healthy contribution experience, and easier reasoning behind the publish pipeline as of now, with margin to revisit this later as our needs expand.

Thanks to everyone involved in this discussion 🚀