Fabric Repo Automation

This guide demonstrates how to automate releases in FINN/Fabric repositories using Semantic Release and Github Actions. To read more about how releases in Fabric work, please refer to the RFC.

Setup

1. Create a next branch from the default branch.

2. Setup and configure renovate bot to auto merge dependencies to the next branch:

If your app has a renovate.json file in the root of the project, delete this file and create a new file .github/renovate.json with the following contents:

.github/renovate.json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["github>podium-lib/renovate-presets:top-level-module"],
  "baseBranches": ["next"],
  "lockFileMaintenance": {
    "automerge": true
  }
}

We use baseBranches to tell renovate to open PRs against the next branch instead of the default main branch. The extends option tells renovate to inherit configuration options from this file. That's it. Now renovate is fully configured. Easy, eh?

3. Add commitizen to ensure conventional commits are used

Run npm install -g commitizen to install the commitizen cli tools.

Then initialize the project to use the commitizen by running commitizen init cz-conventional-changelog --save-dev --save-exact. To understand what this does, please refer to the commitizen documentation.

Now our project should be running commitizen and you can type cz or git cz in your terminal to commit changes.

4. Setup Semantic Release to auto publish from the default and next branch with auto generated release notes

Semantic Release has difficulties understanding repositories using SSH urls. To get around this, update your package.json with the following:

"repository": {
  "type": "git",
  "url": "https://github.com/fabric-ds/REPO_NAME.git"
},

Before running the following command, take note of the current package version number in package.json as this will be automatically changed by the following command. We want to revert this change after.

Then in the root of your project run npx semantic-release-cli setup and follow the setup process step by step.

When prompted to authenticate, please use the shared FINNFPW account for Github and NPM.

You will need to create a GitHub Personal Access Token, you can create one here. Make sure you use the FINNFPW account and give it the appropriate repository permissions. 90 days. Name the token something like Semantic Release REPO_NAME.

The end result should look something like this:

FYI: These tokens have been invalidated.

Now in your package.json you want to revert the version field update as this was automatically changed to:

"version": "0.0.0-development"

Change it back to the latest published version.

+  "version": "0.9.2",
-  "version": "0.0.0-development",

Now create a release.config.cjs in the root of your repo with the following content:

release.config.cjs

module.exports = {
  branches: [{ name: 'main' }, { name: 'next', prerelease: true }],
  preset: 'angular',
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    '@semantic-release/changelog',
    [
      '@semantic-release/npm',
      {
        tarballDir: 'release',
      },
    ],
    [
      '@semantic-release/github',
      {
        assets: 'release/*.tgz',
      },
    ],
    [
      'semantic-release-slack-bot',
      {
        notifyOnSuccess: false,
        notifyOnFail: false,
        packageName: '@fabric-ds/REPO_NAME',
        branchesConfig: [
          {
            pattern: 'main',
            notifyOnSuccess: true,
            onSuccessTemplate: {
              text: ':tada: $package_name@$npm_package_version is now available - $repo_url. \n $release_notes',
            },
          },
        ],
      },
    ],
    '@semantic-release/git',
  ],
};

NB Change REPO_NAME with the package name, e.g. css.

Then install the missing semantic-release dependencies by running the following command:

npm install @semantic-release/changelog @semantic-release/git semantic-release-slack-bot -D

5. Set up a Github Action to release on push/merge to main or next

Add the following scripts to your package.json file

"eik:login": "npx @eik/cli login",
"eik:publish": "npx @eik/cli publish",

Then create a .github/workflows/release.yml file with the following contents:

.github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main
      - next

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16.x'
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
        run: npx semantic-release
      - name: Eik login and publish
        run: npm run eik:login -k $EIK_TOKEN && npm run eik:publish || true
        env:
          EIK_TOKEN: ${{ secrets.EIK_TOKEN }}

6. Optional: Add a section to the README.md explaining how releases work. See example in fabric-ds/react.

7. 🎉 All done! Try merging something in to next and watch the magic happen.