Introduce Changesets

[alessbell]

This PR introduces a .changeset/config.json and three GitHub workflows to begin the process of automating releases of @apollo/client🎉

Prereleases

In .github/workflows/prerelease.yml, pushes to release-* integration branches typically used for assembling minor releases cause the branch to enter changeset's prerelease mode which creates a .changeset/pre.json file.

Each commit to a release branch that contains a changeset (created on the feature branch before merging into the release branch via npx changeset) will create a new branch prefixed with changeset-release/ and open an automated PR that looks like this:

The changeset-release/* PR contains a diff that:

• increments the version with the auto-incrementing alpha number
• updates the CHANGELOG
• adds the changeset to the list being tracked in pre.json

In this example, merging the automatically created PR will release version 1.4.0-alpha.2 at the alpha tag only on npm (we intentionally do not create GitHub releases for alphas) 🚀

Again, commits that do not add new changesets will not trigger an automated PR. When work on our release branch is completed, the next step is to exit prerelease mode.

Exiting Prerelease mode

Changeset has an API for exiting prerelease mode that doesn't quite fit our workflow, so I've taken a different approach in .github/workflows/exitPrerelease.yml. The problem with changeset pre exit is that it sets "mode": "exit" in pre.json, but leaves the file in place to be merged into the default branch, where changeset version would theoretically later get run (unless it's being run manually, which seems to defeat the purpose).

This would lead to pre.json being repeatedly committed and removed from the main branch, and I'm of the opinion that we want to avoid the possibility of main ever being in pre mode, so we should avoid merging the file altogether.

Instead, .github/workflows/exitPrerelease.yml can be run via GitHub actions UI using the workflow dispatch API:

In our example, if we were to enter "release-1.4", the following changes would be be committed to our release branch:

pre.json is removed and the version in package.json reverts to the last release from main. This leaves our changesets to be committed to main where our .github/workflows/release.yml workflow will pick them up and open an automated PR for the release, just as if we had committed a patch changeset directly to main.

Releases

Changesets that are merged into main trigger an automated PR, just as on the release branch, but merging these PRs create:

1. a new GitHub release, which are not created for prereleases
2. a new npm release at the next tag

A few things to note

• For now, I've set this up to publish to next at which point we can run e.g. npm dist-tag add @apollo/client@3.8.0 latest locally to promote it to latest, but we can opt to release straight to latest in the future.
• We can add a check to make sure pre.json doesn't get committed to main, but the downside is that release branches will appear to be failing their status checks until we exit prerelease mode. This has been added in a727a56.
• After merging a release branch, the automatically created PR can be pulled down where we can edit the CHANGELOG. Alpha releases are entered into CHANGELOG.md and we can remove them if we like (see Apollo Server example and @glasser's commit ttps://github.com/apollographql/apollo-server/pull/7017).

[alessbell]

Taken from https://github.com/apollographql/apollo-server/blob/6b4674dd80747a6a5f13ca9f4ca9ed5b0ee77813/.circleci/config.yml#L89 :)

An example of a PR with a failing changesets check: apollographql/apollo-server#7229

[glasser]

We can add a check to make sure pre.json doesn't get committed to main, but the downside is that release branches will appear to be failing their status checks until we exit prerelease mode.

You can simply only have the check fail on release branches?

After merging a release branch, the automatically created PR can be pulled down where we can edit the CHANGELOG. Alpha releases are entered into CHANGELOG.md and we can remove them if we like (see Apollo Server example and @glasser's commit apollographql/apollo-server#7017).

Note that there's kinda two things here (I suspect you understand this but maybe this will be helpful for others):

• If you edit the CHANGELOG on the changeset-release branch itself (ie, the branch created by the changeset action) before you merge it, then those changes to the CHANGELOG will actually affect the text of the GitHub release created when changelog publish creates the release after you merge. So it's a nice place if you want to add some extra text before the list of changes, etc.
• On the other hand, the only time that the changeset automation reads from the CHANGELOG file is to read that first section at the time it creates the GitHub release — so you can always happily update or remove old sections later if you'd like without having to worry about breaking anything.

[alessbell]

You can simply only have the check fail on release branches?

Agree - I was more referring to the fact that while the release-x.x branch is in prerelease mode (for most of the time it's open) it will show up as failing its checks with a big ❌ in the PR list view. But I actually think it's a check worth having to avoid accidentally merging early, so I'll add it to this PR - any strong opinions here @jerelmiller @bignimbus?

Note that there's kinda two things here (I suspect you understand this but maybe this will be helpful for others):

Glad you brought up these points as they're important to note :)

[bignimbus]

So exciting! 🚀

I have no specific feedback about the settings there, they all look sensible to me

[changeset-bot]

⚠️ No Changeset found

Latest commit: f3d129f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jerelmiller]

I actually think it's a check worth having to avoid accidentally merging early

@alessbell I agree. The more we can protect ourselves, the better. Mistakes happen and the more we can prevent them, the better. Nice work getting this in there!

[jerelmiller]

💯 💯 💯 🔥 🔥 🔥

This is such a positive change. Thanks so much for getting this in there!