[RFC]: Use Changesets to manage a changelog

[jtoar]

Release notes are super important, but take a lot of time if done completely by hand. A lot of the work that goes into release notes is manual and should be automated, such as copy and pasting PR numbers and titles.

Changesets streamlines release notes by including a mini changelog per PR (a "changeset" I guess), written by either the contributor or a maintainer. When it comes time to release, all the changesets can be used as the basis for release notes. Moreover, we'll maintain a rolling changelog!

We can also use changesets to cut a release.

TODO

• [ ] what's the correct config?
• [ ] update contributing docs on how to use changesets when opening a PR
• [ ] do we want to use changesets to cut releases?
• [ ] if we use this, we should install the bot on this repo too

[peterp]

Nice, I would love to see what a changeset looks like?

[thedavidprice]

@peterp I saw it being used by The Guild and asked Dom to explore as an option. Still new to me as well. Here's the associated bot activity in a Guild PR: https://github.com/dotansimha/envelop/pull/276#issuecomment-860244103

My understanding so far is that it logs PR changes via markdown in the dir .changeset/. See this example: https://github.com/dotansimha/envelop/pull/276/files#diff-5b3cca0b7b8021fcd6cd3a16126a48f38acd53365bc63db132de493e27f6c8a4

And I think it's possible to organize that directory either per-package or per-repo (or both). Then we can decide how we want to use the changeset markdown files for release notes, changelog, etc.

@jtoar correct me where I'm wrong.

[peterp]

Oh, I meant more as a contributor that produces change-sets? Is there anything that I need to do differently?

[jtoar]

@peterp I'll add a tape showing the workflow shortly!

[jtoar]

@peterp @thedavidprice yes and no—changesets basically gives contributors (and/or maintainers!) the option to add metadata to their PR. here's a walkthrough of what using changesets would entail: https://s.tape.sh/oqUXihjj. Note that I haven't looked into releasing and publishing with it yet.

[jtoar]

Here's one way to do releasing with it, via a github action: https://github.com/changesets/action. The action opens a PR, and when we're ready to release, we merge the PR. The packages get published to npm automatically.

The PR gets updated when changesets are added to main.

We could do it manually too though of course!

[jtoar]

I've seen this option used in a lot of repos using changesets (xstate, mobx):

"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {    
  "onlyUpdatePeerDependentsWhenOutOfRange": true  
}

Not sure I fully understand it yet but seems like something we should consider / might run into down the line if we choose to use this.

[dotansimha]

@peterp I saw it being used by The Guild and asked Dom to explore as an option. Still new to me as well. Here's the associated bot activity in a Guild PR: dotansimha/envelop#276 (comment)

I can honestly say that Changeset is working great for us. For all our repos.

My understanding so far is that it logs PR changes via markdown in the dir .changeset/. See this example: dotansimha/envelop#276 (files)

Yeah, the files are stored in the repo, and deleted when you merge the "release" PR, which leads also to a version bump, and then publish to npm with a changelog.

Also, we have a custom implementation for canary releases. We have a custom script (you can find it here: https://github.com/dotansimha/envelop/blob/main/scripts/canary-release.js) that knows how to read the changesets, and it runs as part of PRs only (see https://github.com/dotansimha/envelop/blob/main/.github/workflows/canary.yml). So in each PR we get alpha release for the changes packages ;)

If you wish to use that setup as well, ping me, maybe we can collaborate on an extension for changesets that will be a nice fit for both us as well :)

[peterp]

This is rad, let's get it in!

[thedavidprice]

@jtoar Let's sync up on this one real-time and get it in. I just want to make sure I'm on the same page about how we're going use this so I can help manage + evaluate the experiment.

[thedavidprice]

@jtoar let's revisit this week

[jtoar]

I know we still want to get better changelog support of some kind per PR, but switching to changesets would be a bit extreme given our lerna workflow. I'd like to close this just to clean up, and keep track of this as a project elsewhere.