release-management.yml

name: Release Management

on:
  push:
    branches: [ master ]

jobs:
  test_and_build:
    name: Test and build
    runs-on: ubuntu-20.04
    outputs:
      version: ${{ steps.check_package_version.outputs.version }}
      version_changed: ${{ steps.check_package_version.outputs.changed }}
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm test

      - name: Build
        run: npm run build

      - name: Check package.json for version change
        id: check_package_version
        uses: EndBug/version-check@v2

      - name: Log when version changed
        if: steps.check_package_version.outputs.changed == 'true'
        run: 'echo "Version change found in commit ${{ steps.check_package_version.outputs.commit }}! New version: ${{ steps.check_package_version.outputs.version }} (${{ steps.check_package_version.outputs.type }})"'

      - name: Log when version unchanged
        if: steps.check_package_version.outputs.changed == 'false'
        run: 'echo "No version change"'

  update_release_draft:
    name: Update release draft
    permissions:
      contents: write
    needs: [test_and_build]
    if: needs.test_and_build.outputs.version_changed == 'false'
    runs-on: ubuntu-20.04
    steps:
      - name: Draft release on GitHub
        uses: release-drafter/release-drafter@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  publish_release_draft_on_version_bump:
    name: Publish release draft
    needs: [test_and_build]
    if: needs.test_and_build.outputs.version_changed == 'true'
    runs-on: ubuntu-20.04
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      # An existing release draft is published only if there is a version bump in `package.json`.
      # Throws an error and breaks the job if called regardless. We check for version changes in the
      # `test_and_build` job first so this job is skipped rather than exited with an error.
      - name: Publish matching GitHub release draft
        id: github_release
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
        run: gh release edit "v${{ needs.test_and_build.outputs.version }}" --draft=false

      - name: Write out the release URL
        run: echo "Released at $RELEASE_URL"
        env:
          RELEASE_URL: ${{ steps.github_release.outputs.release_url }}

  publish_package_to_npm:
    name: Publish to npm
    needs: [test_and_build, publish_release_draft_on_version_bump]
    if: needs.test_and_build.outputs.version_changed == 'true'
    runs-on: ubuntu-20.04
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
          registry-url: https://registry.npmjs.org

      - name: Install
        run: npm ci

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_PUBLISH_TOKEN}}

  deploy_docs:
    name: Deploy docs
    permissions:
      contents: write
    needs: [test_and_build, publish_release_draft_on_version_bump]
    if: needs.test_and_build.outputs.version_changed == 'true'
    runs-on: ubuntu-20.04
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      # Hard-coded username and email for the GitHub bot user
      # https://api.github.com/users/github-actions%5Bbot%5D
      - name: Configure Git credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install
        run: npm ci

      - name: Build
        run: npm run build

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: Get cache ID
        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV

      - name: Restore cache
        uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-

      - name: Install MkDocs
        run: pip install 'mkdocs-material>=9.0.0,<10.0.0'

      - name: Build and deploy MkDocs
        run: mkdocs gh-deploy --force