How to add 🦋 changesets 🦋 workflow to a simple package repo on GitHub
Recently we decided to start using changesets at work. At this moment we only have one medium size component library package that we maintain but we plan to add more in the near future.
Since I was not able to find a quick guide to how to add this workflow to our simple package repo I decided to create my own.
If you don't know what is a changeset I strongly recommend to check the official document here.
Note: This guide is meant for being used to add the changesets workflow to a fresh new project but with some minor tweaks you could apply it to an existing project.
TL:DR Check the example repo
Let's get into it!
Add dependencies
First of all we need to install some dev dependencies that we would be using as part of our workflow and our GitHub actions.
On the root of your project run:
yarn add -D @changesets/cli @changesets/changelog-github
Config our changesets
Then we are going to init our changesets folder:
yarn changeset init
This command would create a new folder into the root of our project called .changesets
containing a README.md
and a config.json
file. The README.md
explains a little bit the purpose of this folder and we don't need to care about it.
Now we are going to make some minor tweaks to our .changesets/config.json
file to have a nice and polish 💅CHANGELOG.md
file.
The changelog
property would allow us to choose which package use for creating our CHANGELOG.md
file. Since we are on GitHub let's use the package that we already install. You would need to provide as a second argument an object with the repo owner and project name. This way our changelogs would have GitHub information such as which PR introduced a change and the commit hash.
The baseBranch
change is because by default the init command would use master
but new repositories on GitHub would recommend switch to main
(feel free to use whatever you feel the best).
{
"$schema": "https://unpkg.com/@changesets/config@1.6.0/schema.json",
- "changelog": "@changesets/cli/changelog",
+ "changelog": ["@changesets/changelog-github", { "repo": "org/repo" }],
"commit": false,
"linked": [],
"access": "restricted",
- "baseBranch": "master",
+ "baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
It should look similar to this
// .changesets/config.json
{
"$schema": "https://unpkg.com/@changesets/config@1.6.0/schema.json",
"changelog": ["@changesets/changelog-github", { "repo": "maurodaprotis/example-repo" }],
"commit": false,
"linked": [],
"access": "restricted",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
Add scripts to our package.json
Now we are ready to add a few scripts to our package.json
to make our workflow easier!
// package.json
{
...
"scripts": {
... other scripts ...
"changeset": "changeset",
"prerelease": "yarn test && yarn build",
"release": "changeset publish"
},
...
}
So, let's see:
changeset
: would create a new changeset asking the contributor if the change was a patch, minor or major and brief description about the changes made.prerelease
: would run our tests and build command (you should probably have those setup 😉) before running the release script.release
would publish a new version of our package.
Note: These scripts are only a suggestion you could implement yours as you want.
Release GitHub Action
It's time to automate our releases, let's crate a release.yml
file in our GitHub actions folder (.github/workflows
) with the following content:
name: Release
on:
push:
branches:
- main
jobs:
release:
name: Release
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@master
with:
# This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
fetch-depth: 0
- name: Setup Node.js 12.x
uses: actions/setup-node@master
with:
node-version: 12.x
- name: Install Dependencies
run: yarn
- name: Create Release Pull Request or Publish to npm
id: changesets
uses: changesets/action@master
with:
# This expects you to have a script called release which does a build for your packages and calls changeset publish
publish: yarn release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Do something after we publish a new version
if: steps.changesets.outputs.published == 'true'
# You can do something when a publish happens.
run: echo "New version published!"
Final workflow
Now every time you introduce changes on a branch you should run yarn changeset
to create a new changeset file.
Once you branch is merged into main
our GitHub action would generate a PR with all the existing changesets applied to the CHANGELOG.md
file with the correct semver bump.
Finally, when you are ready to release the new version you'll only need to merge it and Voila! a new version would be published.
Extra: Add Changesets bot
You could add the changeset bot 🤖 to your project to check that each PR includes a changesets file.
Example repo
You can find an example repo here with the configuration listed above.