add changesets release workflow

[RodrigoHamuy]

Fix #764

For this PR to fully work, we need to add the following things first:

• Install the Changesets bot to this repo: https://github.com/apps/changeset-bot
• Add an NPM_TOKEN to this repo secrets.

What this PR and requests action will do:

• Add a comment suggesting to add a changeset file whenever a new PR is created.
• changesets will create or update an existing release PR which takes all the changes since the last release. When you merge one of those auto-generated release PRs it will release to NPM, push a git tag, update the CHANGELOG.md file and release to Github too.
• More info in https://github.com/changesets/changesets/tree/main?tab=readme-ov-file#how-do-i-get-started

[gkjohnson]

Thank you! A few questions:

Add a comment suggesting to add a changeset file whenever a new PR is created.

From here it sounds like it's expected that users run the changeset CLI to generate this changeset file, is that right? Looking at the emotion CHANGELOG it looks like PRs are tagged using labels (see tag: bug fix label in that PR), as well, which must affect the CHANGELOG generation since there are no changesets in those commits. Is this a special or atypical set up?

Add an NPM_TOKEN to this repo secrets.

From the repo settings page it looks like these secrets will be available to anyone who has maintainer access to the repo. Is it typical to have a dedicated publishing bot whose secrets are used for this purpose?

[RodrigoHamuy]

From here it sounds like it's expected that users run the changeset CLI to generate this changeset file, is that right?

Yes, the user can run npm run changesets locally or the Changeset bot will offer to create the changeset file via GH UI (example). This will generate an .md file in the .changeset folder. It looks like this:

---
"@changesets/cli": major
---

A description of the major changes.
If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine.

You can have as many of these files as needed, and you can alter them in the PR or at any time after too, as long as you haven't "release", you can modify these files whenever.

The release.yml workflow will always create or update a release PR whenever changes are made to master. This PR will delete all the .changeset/**.md files and copy their content to CHANGELOG.md and calculate what should be the next version of the package, updating it also in the package.json version property. Here is a "release PR" example.

From the repo settings page it looks like these secrets will be available to anyone who has maintainer access to the repo. Is it typical to have a dedicated publishing bot whose secrets are used for this purpose?

The Changeset bot only adds a comment to PRs, it never has access to the secret token. Its purpose is only to add a little changeset comment to PRs, so the PR author has a bit more context about what they need to do to affect a release. It will suggest add the .changeset/**.md file if not present, otherwise will tell you how it will impact the next release if the file is already present. You can check any PRs from other projects that uses changesets, like this one. I realise I didn't explain this correctly earlier, sorry for the confusion!

The actual PR and release are handled by the release.yml workflow.

Only Github workflows can see the NPM_TOKEN, nobody else can including you after setting it up. If you try to see on the Github workflow logs it will be masked.

And the way you have set up the repo, only you can choose who/when Github workflows can run. At the moment even this PR is still waiting for workflow approval to run.

There will always be a risk of malicious use like with any other security setup, but the risk is relatively low.

Is it typical to have a dedicated publishing bot whose secrets are used for this purpose?

Yes, it is a fairly common practice. Probably most of these projects are doing this. But that's a requirement for any automated CI/CD, not of changesets in particular. For example, if you decide to use a different automated CI/CD solution, chances are that it will still need an NPM token stored in some service, not something that we can avoid if we want automation sadly.

Hope this makes sense! I know it seems super complicated but the actual day to day use is very simple in practice.

[gkjohnson]

Thanks Rodri - after thinking about this for a bit I think this will wind up adding more overhead for me when making releases. If / when the project grows larger then maybe it will be worth reconsidering. But I appreciate you laying it all out - this is a topic I wasn't familiar with previously.

[RodrigoHamuy]

Sounds good, @gkjohnson . If you change your mind, I personally think this actually reduces overhead as now you only need to click "merge PR" whenever you want to release, as oppose to packing and publishing things manually and on a device with NPM logging details.

But totally get this isn't everybody style, so if this is a close matter, feel free to close the PR :)

Also, this is really a minor thing, the real work is the library itself and is nothing but amazing so far 🤩