feat(release): add beta channel and docs automation (#56)

* feat(release): add beta channel and docs automation

* fix(release): repair changelog and dry-run CI

* fix: apply CodeRabbit auto-fixes

Fixed 1 file(s) based on 2 unresolved review comments.

Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

Author: 3 people

.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - master
+      - main
+      - beta
+  push:
+    branches:
+      - master
+      - main
+      - beta
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate on Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22, 24]
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Smoke-load release config
+        run: npm run test:config
+
+      - name: Check docs index
+        run: npm run docs:index:check
+
+  semantic-release-dry-run:
+    name: semantic-release dry run
+    runs-on: ubuntu-latest
+    needs: validate
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run semantic-release in dry-run mode
+        run: npm run release:dry-run

.github/workflows/codeql-analysis.yml

@@ -13,10 +13,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, main ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master ]
+    branches: [ master, main ]
   schedule:
     - cron: '18 1 * * 0'
 
@@ -39,11 +39,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -54,7 +54,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -68,4 +68,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v3

.github/workflows/release.yml

@@ -4,23 +4,30 @@ on:
   push:
     branches:
       - master
+      - main
+      - beta
 
 jobs:
   publish:
-    name: Publish to Github & NPM or Github Package Registry
+    name: Publish to GitHub and npm
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
-      - env:
-          CI: true
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
         run: npm ci
-      - if: success()
+      - name: Publish release
         env:
           CI: true
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npx semantic-release
+        run: npm run semantic-release

.github/workflows/test-release.yml

@@ -12,59 +12,51 @@ const COMMIT_HASH_LENGTH = 7;
  * @return {Object} the transformed commit.
  */
 module.exports = (commit, context) => {
-	if (commit.notes) {
-		commit.notes.forEach(note => {
-			note.title = 'Breaking changes';
-		});
-	}
-
-	if (types.types[commit.type] && (types.types[commit.type].changelog || (commit.notes && commit.notes.length > 0))) {
-		commit.groupType = `${types.types[commit.type].emoji ? `${types.types[commit.type].emoji} ` : ''}${
-			types.types[commit.type].title
-		}`;
-		commit.type = commit.groupType;
-	} else {
+	const commitType = types.types[commit.type];
+	const notes = Array.isArray(commit.notes)
+		? commit.notes.map(note => ({
+				...note,
+				title: 'Breaking changes',
+			}))
+		: [];
+
+	if (!commitType || (!commitType.changelog && notes.length === 0)) {
 		return null;
 	}
 
-	if (commit.scope === '*') {
-		commit.scope = '';
-	}
-
-	if (typeof commit.hash === 'string') {
-		commit.shortHash = commit.hash.slice(0, COMMIT_HASH_LENGTH);
-	}
+	const groupType = `${commitType.emoji ? `${commitType.emoji} ` : ''}${commitType.title}`;
 
 	const references = [];
+	let subject = commit.subject;
 
-	if (typeof commit.subject === 'string') {
+	if (typeof subject === 'string') {
 		let url = context.repository ? `${context.host}/${context.owner}/${context.repository}` : context.repoUrl;
 
 		if (url) {
 			url += '/issues/';
 			// Issue URLs.
-			commit.subject = commit.subject.replace(/#(\d+)/g, (_, issue) => {
+			subject = subject.replace(/#(\d+)/g, (_, issue) => {
 				references.push(issue);
 				return `[#${issue}](${url}${issue})`;
 			});
 		}
 
 		if (context.host) {
 			// User URLs.
-			commit.subject = commit.subject.replace(/\B@([a-z0-9](?:-?[a-z0-9]){0,38})/g, `[@$1](${context.host}/$1)`);
+			subject = subject.replace(/\B@([a-z0-9](?:-?[a-z0-9]){0,38})/g, `[@$1](${context.host}/$1)`);
 		}
 	}
 
-	if (commit.references) {
-		// Remove references that already appear in the subject
-		commit.references = commit.references.filter(reference => {
-			if (!references.includes(reference.issue)) {
-				return true;
-			}
-
-			return false;
-		});
-	}
-
-	return commit;
+	return {
+		...commit,
+		groupType,
+		type: groupType,
+		scope: commit.scope === '*' ? '' : commit.scope,
+		shortHash: typeof commit.hash === 'string' ? commit.hash.slice(0, COMMIT_HASH_LENGTH) : commit.shortHash,
+		subject,
+		notes,
+		references: Array.isArray(commit.references)
+			? commit.references.filter(reference => !references.includes(reference.issue))
+			: commit.references,
+	};
 };

commit-transform.js

@@ -0,0 +1,7 @@
+# Docs Index
+
+Repository documentation kept in sync by `docs-index-keeper`.
+
+| Doc | Purpose |
+| --- | --- |
+| [release-channels.md](./release-channels.md) | Stable and beta release channel behavior for this repository |

docs/README.md

@@ -0,0 +1,8 @@
+# Release Channels
+
+This repository uses a repo-only semantic-release config to keep package consumers on the shared preset while giving the repository two release channels:
+
+- `master` and `main` publish stable releases on the default `latest` channel during the branch migration window
+- `beta` publishes prereleases with the `beta` dist-tag and `-beta.N` versions
+
+The repo automation uses `release.repo.config.js` so the published shareable config in `release.config.js` does not force prerelease branches on downstream consumers.