How to add  🦋 changesets 🦋 workflow to a simple package repo on GitHub

How to add 🦋 changesets 🦋 workflow to a simple package repo on GitHub

·

4 min read

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.