From eda0d64dad676ac5d7443e2bfe32148d90393f6b Mon Sep 17 00:00:00 2001 From: Sid Vishnoi <8426945+sidvishnoi@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:10:45 +0530 Subject: [PATCH] chore(ci): add release pipeline and documentation (#508) Co-authored-by: Radu-Cristian Popa --- .github/actions/bump-manifest-version.cjs | 50 +++++++++ .github/actions/validate-stable-release.cjs | 40 +++++++ .github/workflows/bump-manifest-version.yml | 51 +++++++++ .github/workflows/release-preview.yml | 63 +++++++++++ .github/workflows/release-stable.yml | 79 ++++++++++++++ cspell-dictionary.txt | 1 + docs/RELEASE.md | 112 ++++++++++++++++++++ tsconfig.json | 1 + 8 files changed, 397 insertions(+) create mode 100644 .github/actions/bump-manifest-version.cjs create mode 100644 .github/actions/validate-stable-release.cjs create mode 100644 .github/workflows/bump-manifest-version.yml create mode 100644 .github/workflows/release-preview.yml create mode 100644 .github/workflows/release-stable.yml create mode 100644 docs/RELEASE.md diff --git a/.github/actions/bump-manifest-version.cjs b/.github/actions/bump-manifest-version.cjs new file mode 100644 index 00000000..622c6fbf --- /dev/null +++ b/.github/actions/bump-manifest-version.cjs @@ -0,0 +1,50 @@ +// @ts-check +/* eslint-disable @typescript-eslint/no-var-requires, no-console */ +const fs = require('node:fs/promises') + +/** @param {import('github-script').AsyncFunctionArguments} AsyncFunctionArguments */ +module.exports = async ({ core }) => { + const manifestPath = './src/manifest.json' + const manifestFile = await fs.readFile(manifestPath, 'utf8') + const manifest = JSON.parse(manifestFile) + /**@type {string} */ + const existingVersion = manifest.version + + const bumpType = /** @type {BumpType} */ (process.env.INPUT_VERSION) + if (!bumpType) { + throw new Error('Missing bump type') + } + + const version = bumpVersion(existingVersion, bumpType).join('.') + + console.log({ existingVersion, bumpType, version }) + + manifest.version = version + await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2)) + core.setOutput('version', version) +} + +/** + * @typedef {'build' | 'patch' | 'minor'} BumpType + * @param {string} existingVersion + * @param {BumpType} type + * @return {[major: number, minor: number, patch: number, build: number]} + */ +function bumpVersion(existingVersion, type) { + const parts = existingVersion.split('.').map(Number) + if (parts.length !== 4 || parts.some((e) => !Number.isSafeInteger(e))) { + throw new Error('Existing version does not have right format') + } + const [major, minor, patch, build] = parts + + switch (type) { + case 'build': + return [major, minor, patch, build + 1] + case 'patch': + return [major, minor, patch + 1, 0] + case 'minor': + return [major, minor + 1, 0, 0] + default: + throw new Error('Unknown bump type: ' + type) + } +} diff --git a/.github/actions/validate-stable-release.cjs b/.github/actions/validate-stable-release.cjs new file mode 100644 index 00000000..d3f3ebd0 --- /dev/null +++ b/.github/actions/validate-stable-release.cjs @@ -0,0 +1,40 @@ +// @ts-check + +/** + * 1. Validate input version. + * 2. Check if given tag/release is already promoted to stable. If so, crash. + * @param {import('github-script').AsyncFunctionArguments} AsyncFunctionArguments + */ +module.exports = async ({ github, context }) => { + if (context.ref !== 'refs/heads/main') { + throw new Error('This action only works on main branch') + } + + const { owner, repo } = context.repo + const previewVersionTag = process.env.INPUT_VERSION + if (!previewVersionTag) { + throw new Error('Missing env.INPUT_VERSION') + } + if (!previewVersionTag.match(/^v[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+-preview$/)) { + throw new Error('Input "version" must match vX.X.X.X-preview') + } + + const versionTag = previewVersionTag.replace('-preview', '') + try { + await github.rest.repos.getReleaseByTag({ + owner, + repo, + tag: versionTag + }) + throw new Error('Release already promoted to stable') + } catch (error) { + if (!error.status) { + throw error + } + if (error.status === 404) { + // do nothing + } else { + throw new Error(`Failed to check: HTTP ${error.status}`, { cause: error }) + } + } +} diff --git a/.github/workflows/bump-manifest-version.yml b/.github/workflows/bump-manifest-version.yml new file mode 100644 index 00000000..77b1c9a2 --- /dev/null +++ b/.github/workflows/bump-manifest-version.yml @@ -0,0 +1,51 @@ +name: Bump Manifest Version + +on: + workflow_dispatch: + inputs: + version: + description: 'Version to bump to' + required: true + default: 'build' + type: choice + options: + - build + - patch + - minor + +permissions: + contents: write + pull-requests: write + +jobs: + bump-version: + name: Bump version + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: { node-version-file: '.nvmrc' } + + - name: Bump version + id: bump + uses: actions/github-script@v7 + env: + INPUT_VERSION: ${{ github.event.inputs.version }} + with: + script: | + const script = require('./.github/actions/bump-manifest-version.cjs') + await script({ github, context, core }) + + - name: Create pull request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: 'chore: release version ${{ steps.bump.outputs.version }}' + title: 'chore: release version ${{ steps.bump.outputs.version }}' + body: | + Bump extension version to ${{ steps.bump.outputs.version }} + branch: preview/${{ steps.bump.outputs.version }} + labels: preview diff --git a/.github/workflows/release-preview.yml b/.github/workflows/release-preview.yml new file mode 100644 index 00000000..45d5a1c5 --- /dev/null +++ b/.github/workflows/release-preview.yml @@ -0,0 +1,63 @@ +name: Release for Preview Channel + +on: + push: + branches: + - main + - 'v[0-9]+.x' + paths: + - 'src/manifest.json' + +defaults: + run: + shell: bash + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: write + +jobs: + release-preview: + if: "${{ startsWith(github.event.head_commit.message, 'chore: release version') }}" + runs-on: ubuntu-latest + # environment: production + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Environment setup + uses: ./.github/actions/setup + + - name: Build + run: pnpm build --channel=preview + + - name: Get built version + uses: actions/github-script@v7 + id: version + with: + script: | + const script = require('./.github/actions/get-built-version.cjs') + await script({ github, context, core }) + + - name: Delete existing release # To keep the workflow idempotent. + run: gh release delete v${{ steps.version.outputs.version }}-preview --cleanup-tag --yes + continue-on-error: true + env: + GH_TOKEN: ${{ github.token }} + + - name: Release + uses: softprops/action-gh-release@v2 + with: + files: | + dist/*.zip + tag_name: v${{ steps.version.outputs.version }}-preview + name: Preview v${{ steps.version.outputs.version }} + prerelease: true + + # - name: Upload to stores + # if: github.ref_name == 'main' + # run: | + # echo 'TODO' diff --git a/.github/workflows/release-stable.yml b/.github/workflows/release-stable.yml new file mode 100644 index 00000000..2bdc6e80 --- /dev/null +++ b/.github/workflows/release-stable.yml @@ -0,0 +1,79 @@ +name: Release Stable +run-name: Release Stable ${{ github.event.inputs.version }} + +on: + workflow_dispatch: + inputs: + version: + description: 'Tag (vX.X.X.X-preview)' + required: true + type: string + +defaults: + run: + shell: bash + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: write + +jobs: + release-stable: + runs-on: ubuntu-latest + # environment: production + name: Release + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + # We want to build extension using the code and dependencies as of + # this tag. The scripts, workflows are back-ported, so they can be + # used consistently. + ref: ${{ github.event.inputs.version }} + + - name: Environment setup + uses: ./.github/actions/setup + + - name: Validate stable release + uses: actions/github-script@v7 + env: + INPUT_VERSION: ${{ github.event.inputs.version }} + with: + script: | + const script = require('./.github/actions/validate-stable-release.cjs') + await script({ github, context, core }) + + - name: Build + run: pnpm build --channel=release + + - name: Get built version + uses: actions/github-script@v7 + id: version + with: + script: | + const script = require('./.github/actions/get-built-version.cjs') + await script({ github, context, core }) + + - name: Delete existing release # To keep the workflow idempotent. + run: gh release delete v${{ steps.version.outputs.version }} --cleanup-tag --yes + continue-on-error: true + env: + GH_TOKEN: ${{ github.token }} + + - name: Release + uses: softprops/action-gh-release@v2 + with: + files: | + dist/*.zip + tag_name: v${{ steps.version.outputs.version }} + name: v${{ steps.version.outputs.version }} + prerelease: false + fail_on_unmatched_files: true + + # - name: Upload to stores + # run: | + # echo 'TODO' diff --git a/cspell-dictionary.txt b/cspell-dictionary.txt index 4a243c63..a891859c 100644 --- a/cspell-dictionary.txt +++ b/cspell-dictionary.txt @@ -24,6 +24,7 @@ linkcode endregion metafile iife +backported # packages and 3rd party tools/libraries awilix diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 00000000..4a05ea39 --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,112 @@ +# Web Monetization Extension Release Pipeline + +Two channels of the extensions will be maintained: + +- Preview +- Stable + +A separate Nightly release channel will be available via GitHub releases (without publishing to stores). + +## Extension versioning + +Web extensions do not follow SEMVER. The version string consists of 1 to 4 numbers separated by dots, for example, `1.2.3.4` (`major.minor.patch.build`). This is essentially SEMVER but with an additional build number, but does not support the alpha, beta or other suffixes. + +### Major version bump + +A major version bump (`2.0.0.0`) signifies the start of a block of product features. + +Before the extension is available first on the Stable channel, we only increase the build number (`2.0.0.x`) when publishing to the Preview channel. After that (during maintenance mode), we follow SEMVER (`2.x.y.0`). + +### Minor version bump + +New features and enhancements will be released under a minor version bump. + +### Patch version bump + +Bug fixes, performance and small updates will be released under a patch version bump. + +### Build version bump + +The build version bump should only happen when starting the work on a new major version. Once a major version (e.g. `v1`) goes into maintenance mode, the extension major version is bumped to `2.0.0.0`. Until the new major version is made available on the Stable channel, only build number should be incremented. + +Multiple "build" version bumps can be made available in the Preview channel. e.g. we can have `2.0.0.1`, `2.0.0.2`, ..., `2.0.0.90` in the Preview channel before we make it available in the Stable channel. + +When the new major version is going to be available in the Stable channel, it will have the last published version as in the Preview channel (i.e. the first Stable channel build could be `2.0.0.90`, not necessarily `2.0.0` or `2.0.1`). + +## Nightly + +The Nightly version will be built every day (except Sundays) at 12AM UTC and it will be added to GitHub releases with the tag `nightly`. + +Nightly releases will correspond to the latest commit in the `main` branch of the repository at the time of the build. The tag reference will get updated on every release (rolling tags). Whenever a new release is happening, the previous one gets deleted first. + +### Versioning for the Nightly build + +On every action run, the workflow will update the following properties in the manifest: + +- `version`: will be set to the current date in `YYYY.M.D` format (note: not `YYYY.MM.DD` as we cannot have zero as prefix in these numbers) +- `version_name`: will be set to `Nightly YYYY.M.D` + +### Release artifacts + +Artifacts follow the name: `nightly-{browser}-{version}.zip`, e.g. `nightly-chrome-2024.7.13.zip`, `nightly-edge-2024.7.13.zip`, `nightly-firefox-2024.7.13.zip` + +## Preview + +The Preview version represents a release candidate on the `main` branch. They are less stable than the Stable version. + +Releases are triggered manually (via GitHub Actions), and can have a minor/patch/build version bump. + +Once a new development stage starts for a new major version and we start publishing it to the Preview channel, we will not be able to push an older version to the Preview channel - they will only be available in GitHub. But the releases for the older version are to be promoted to Stable immediately. + +### Release artifacts + +Artifacts follow the name `preview-{browser}-{version}.zip`, e.g. `preview-chrome-1.0.4.0.zip`, `preview-edge-2.0.0.12.zip`, `preview-firefox-2.1.1.0.zip` + +## Release + +Some of the releases from the Preview channel (that are considered stable enough) are **promoted** to the Stable channel. + +Release promotions are triggered manually (via GitHub Actions). + +### Release artifacts + +Artifacts follow the name `{browser}-{version}.zip`, e.g. `chrome-1.0.4.0.zip`, `edge-2.0.0.12.zip`, `firefox-2.1.1.0.zip`. + +--- + +## Branching strategy + +Whenever a major version goes into maintenance mode, `v{major}.x` is branched-off `main` (e.g. when we work at `v2`, we split a `v1.x` branch from `main`, and then `main` will correspond to `v2.x`). The maintenance branch will mostly receive bug fixes and security updates. Changes to the build process must be back-ported to maintenance branches, to keep workflows consistent. + +We primarily work over the `main` branch. For the maintenance of previous major versions, PRs can be sent to the `v{major}.x` branch. If some commits from the `main` branch need to be available on an earlier major version as well, they can be back-ported (after being merged into `main`) by sending a PR with the other major branch (e.g. `v1.x`) as base. + +## Pull requests + +When there's a commit that needs to be back-ported, the PR corresponding to that commit should have a "needs backport" label. Once back-ported, the label should be removed (or replaced with "backported"). + +--- + +# Release Workflow + +## Releasing to Preview channel + +1. Visit ["Bump Manifest Version" manual dispatch workflow](https://github.com/interledger/web-monetization-extension/actions/workflows/bump-manifest-version.yml) and click the "Run workflow" button. + - Choose the version bump - build, patch, or minor as described above. + - For branch, choose `main` (default) if releasing for the latest major version. Otherwise, select the required `v{major}.x` branch. + - When releasing for a `v{major}.x` branch: + - The extension will not be uploaded to the extension web stores' Preview channel. + - As the extension won't be available on the web store's Preview channel, the [GitHub Release](https://github.com/interledger/web-monetization-extension/releases/) can be shared if testing is required before the promotion to the Stable channel. +1. Validate and approve PR sent from workflow. + - Do not update the PR/commit title. + - Squash and merge the PR. +1. Extension will be released automatically (via ["Release for Preview Channel" workflow](https://github.com/interledger/web-monetization-extension/actions/workflows/release-preview.yml)) as the PR is merged. + - If there's a temporary failure in the action run, re-run the workflow. + +## Releasing to Stable channel + +To promote a Preview channel release to Stable: + +1. Run the ["Release Stable" manual-dispatch workflow](https://github.com/interledger/web-monetization-extension/actions/workflows/release-stable.yml). + - Specify the Preview version tag that should be promoted to Stable, e.g. `v1.2.3.5-preview`. + - Do not change the branch from "main". +1. Extension will be released on as the workflow runs. diff --git a/tsconfig.json b/tsconfig.json index 220b0cb4..bcc0319d 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -28,6 +28,7 @@ "./jest.config.ts", "./jest.setup.ts", "./scripts/**/*", + "./.github/actions/*.cjs", "esbuild/**/*" ], "exclude": ["dist", "dev"]