Semantic releases

Semantic versions are an inherent element of every project and repository. A detailed description of how we create releases and semantic versions can be found on the semantic-release website. This documentation only provides basic instructions for semantic versions.

Tasks

When creating the next version, there should be:

• bump the version in package.json to the actual release version;
• creating a release package on github;
• creating an release tag;
• generating a file of changes containing information about the issue (changelog);
• publishing changes to the repository;
• optional - publication in NPM;

Configuration

The configuration consists of two parts. In the first one, we install the semantic-release packages, and in the second one, we set up the appropriate workflow in Github Actions.

Installation of necessary packages:

npm i -D semantic-release @semantic-release/{git,changelog}

INFO

Plugins commit-analyzer, release-notes-generator, npm, github are part of semantic-release and do not have to be installed separately.

In package.json file should be added:

{
  "release": {
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      [
        "@semantic-release/npm",
        {
          "npmPublish": false
        }
      ],
      "@semantic-release/changelog",
      "@semantic-release/git",
      "@semantic-release/github"
    ],
    "branches": ["main"]
  }
}

If we need to publish in NPM, of course, we can set the value true for npmPublish. The above fragment can also be added to a special configuration file called .releaserc, placed in the root folder of the repository and containing:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/npm",
      {
        "npmPublish": true
      }
    ],
    "@semantic-release/changelog",
    "@semantic-release/git",
    "@semantic-release/github"
  ],
  "branches": ["main"]
}

Workflow file

The basic workflow file for issuing the version is found in .github/workflows/release.yml:

name: Release
on:
  push:
    branches:
      - main
jobs:
  release:
    name: release
    runs-on: ubuntu-latest
    steps:
      - name: Start
        uses: actions/checkout@v3
      - name: Setup
        uses: actions/setup-node@v3
        with:
          cache: npm
          node-version: 16
      - name: Install dependencies
        run: npm ci
      - name: Run build 🔧
        run: npm run build
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm run semantic-release

Setting of variables

The basic environmental variables required for proper semantic issuing are GitHub and NPM tokens. They are required in the file .github/workflows/release.yml.

GITHUB_TOKEN

The Githuba token is a token generated for the user in his account settings. To get it user need:

• go from the user menu (upper right corner, clicking on the avatar) to user profile;
• in the left side menu, select the link: Developer settings;
• in the left side menu, select the link: Personal access tokens;
• above the list of available tokens, click the Generate new token button to proceed to create new token;
• when creating a token, you must define what the token will be used for (Note), provide the expiration time (Expiration), and define the scope of permissions for the token (Select scopes, check the workflow option)
• after creating a token, it must be copied and saved locally because it is displayed only once;

The token obtained above must then be placed in the repository to be used in the Github Actions workflow file:

• go to the repository settings (Settings tab);
• in the left side menu, click the Secrets link and then Actions;
• after going to the page with the list of secret data, click the New repository secret button;
• after going to the adding form page, fill in the Name field (enter GH_TOKEN) and the Secret field (paste the token previously obtained in the user settings);

Once added, the repository workflow recognizes the user token for Github (secrets.GH_TOKEN).

NPM_TOKEN

The token for NPM is mandatory, but remember that in the release settings we decide whether the release will be published to NPM. To obtain it you need to:

• log in to NPM;
• go to the Access Token tab in the user profile and click the Generate New Token button;
• choose what token we want to generate (it should enable publication);
• after creating a token, it must be copied and saved locally because it is displayed only once;

The token obtained above must then be placed in the repository in a similar way to the Github token, with its name being NPM_TOKEN (secrets.NPM_TOKEN).

Versioning

Semantic versioning allows you to generate version numbers that represent the development of your project. The version number is created according to the formula MAJOR.MINOR.PATCH, where:

• MAJOR - when you make incompatible changes to the API, the change occurs and may cause backward incompatibility;
• MINOR - when functionality is added in a backward-compatible manner;
• PATCH - when you make backward compatible bug fixes.

According to SamVer you can in [prerelease configuration](https://semantic-release.gitbook.io/semantic-release/usage/workflow- configuration#prerelease) set additional elements in the generation related to prerelease versions, e.g. alpha, beta, rc.