doc(contributing): improve guidance and examples (#427)

Co-authored-by: Augustin Mauroy <97875033+AugustinMauroy@users.noreply.github.com>

Author: JakobJingleheimer

.github/dependabot.yml

@@ -11,20 +11,22 @@ updates:
 
   - package-ecosystem: github-actions
     commit-message:
-      prefix: ci
+      prefix: dep
     directory: /
     labels:
+      - "dependencies"
       - "gh actions"
     schedule:
       interval: monthly
 
   - package-ecosystem: npm # See documentation for possible values
     commit-message:
-      prefix: deps
+      prefix: dep
     directories:
       - / # Location of package manifests
       - /recipies/*
     labels:
+      - "dependencies"
       - "npm"
     schedule:
       interval: weekly

.github/scripts/pr-prefixes.ts

@@ -0,0 +1,13 @@
+/**
+ * The subset of conventional commit prefixes used in this project.
+ */
+export const SUPPORTED_PREFIXES = [
+	'doc',
+	'dep',
+	'fix',
+	'feat',
+	'setup',
+	'test',
+] as const;
+
+export const SCOPE_RGX = new RegExp(`^(${SUPPORTED_PREFIXES.join('|')})\\([\\w\\-\\d]*\\)\\: `);

.github/scripts/pr-title.test.ts

@@ -0,0 +1,79 @@
+import { equal, match } from 'node:assert/strict';
+import { execPath } from 'node:process';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { spawnPromisified } from '../../utils/src/spawn-promisified.ts';
+
+import { SUPPORTED_PREFIXES } from './pr-prefixes.ts';
+
+describe('Pull Request checks', { concurrency: true }, async () => {
+	const encoding = 'utf8';
+	const prTestPath = fileURLToPath(import.meta.resolve('./pr-title.ts'));
+
+	for (const prefix of SUPPORTED_PREFIXES) {
+		describe(prefix, () => {
+			it('should pass when valid', async () => {
+				const { code, stderr } = await spawnPromisified(
+					execPath,
+					[prTestPath],
+					{
+						encoding,
+						env: { PR_TITLE: `${prefix}(DEP0000): update …` },
+					},
+				);
+
+				equal(stderr, '');
+				equal(code, 0);
+			});
+
+			it('should fail when missing scope', async () => {
+				const { code, stderr } = await spawnPromisified(
+					execPath,
+					[prTestPath],
+					{
+						encoding,
+						env: { PR_TITLE: `${prefix}: update …` },
+					},
+				);
+
+				match(stderr, /AssertionError/);
+				match(stderr, new RegExp(prefix));
+				match(stderr, /pull request title/i);
+				equal(code, 1);
+			});
+
+			it('should fail scope is misformatted', async () => {
+				const { code, stderr } = await spawnPromisified(
+					execPath,
+					[prTestPath],
+					{
+						encoding,
+						env: { PR_TITLE: `${prefix}(DEP0000) update …` },
+					},
+				);
+
+				match(stderr, /AssertionError/);
+				match(stderr, new RegExp(prefix));
+				match(stderr, /pull request title/i);
+				equal(code, 1);
+			});
+		});
+	}
+
+	describe('unsupported prefix', () => {
+		it('should fail', async () => {
+			const prefix = 'foo';
+			const { code, stderr } = await spawnPromisified(execPath, [prTestPath], {
+				encoding,
+				env: { PR_TITLE: `${prefix}(DEP0000): update …` },
+			});
+
+			match(stderr, /AssertionError/);
+			match(stderr, new RegExp(prefix));
+			match(stderr, /pull request title/i);
+			for (const p of SUPPORTED_PREFIXES) match(stderr, new RegExp(p));
+			equal(code, 1);
+		});
+	})
+});

.github/scripts/pr-title.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import { env } from 'node:process';
+
+import { SCOPE_RGX, SUPPORTED_PREFIXES } from './pr-prefixes.ts';
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+			PR_TITLE: string;
+		}
+	}
+}
+
+const { PR_TITLE } = env;
+
+const INVALID_PR_TITLE_ERR = '\
+The pull request title did not match the required format; see CONTRIBUTING.md for details.\
+';
+
+assert.match(PR_TITLE, SCOPE_RGX, INVALID_PR_TITLE_ERR);
+const firstParen = PR_TITLE.indexOf('(');
+const prefix = PR_TITLE.slice(0, firstParen);
+
+assert.ok(
+	SUPPORTED_PREFIXES.includes(prefix),
+	`The pull request title prefix '${prefix}' is not in the supported list: '${SUPPORTED_PREFIXES.join("', '")}'`,
+);

.github/workflows/pr.yml

@@ -0,0 +1,38 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: PR Checks
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - edited
+      - opened
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  check-title:
+    name: PR title (Conventional Commit)
+    runs-on: ubuntu-slim
+
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
+
+    steps:
+      # FIXME https://github.com/step-security/harden-runner/issues/627
+      # - name: Harden Runner
+      #   uses: step-security/harden-runner@fe104658747b27e96e4f7e80cd0a94068e53901d # v2.16.1
+      #   with:
+      #     egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Check prefix
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: node .github/scripts/pr-title.ts

.github/workflows/workflow-tests.yml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+# For more information see: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow
+
+name: Workflow Quality Assurance
+
+on:
+  push:
+    branches: ["*"]
+    paths:
+      - ".github/workflows/*.yml"
+      - ".github/scripts/*"
+  pull_request:
+    branches: ["*"]
+    paths:
+      - ".github/workflows/*.yml"
+      - ".github/scripts/*"
+    types:
+      - opened
+      - ready_for_review
+      - reopened
+      - synchronize
+
+permissions:
+  contents: read
+
+jobs:
+
+  run-workflow-script-tests:
+    name: test scripts
+    runs-on: ubuntu-slim
+
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
+
+    steps:
+      # FIXME https://github.com/step-security/harden-runner/issues/627
+      # - name: Harden the runner (Audit all outbound calls)
+      #   uses: step-security/harden-runner@fe104658747b27e96e4f7e80cd0a94068e53901d # v2.16.1
+      #   with:
+      #     egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          show-progress: false
+
+      - run: node --test ./github/scripts/*.test.ts

CONTRIBUTING.md

@@ -191,13 +191,18 @@ Format:
 ```
 
 - **`type`**: The type of change (e.g., `feat`, `fix`, `docs`, `chore`, etc.)
-- **`scope`**: A short, lowercase description of the section of the codebase affected (e.g., `tmpDir-to-tmpdir`, `esm-migration`)
-- **`description`**: A concise summary of the change
+- **`scope`**: A short, description of the section of the codebase affected;
+  - if introducing a migration handling
+    - a deprecation, the deprecation code (e.g. `DEP0000`)
+    - a non-deprecation, such as facilitating adoption of a node API from a 3rd party, `adopt`
+  - if adjusting an existing migration, the migration's name (e.g. `tmpDir-to-tmpdir`)
+- **`description`**: A concise summary of the change, citing relevant APIs (e.g. `jest-to-node-test-runner`)
 
 Examples:
-- `feat(tmpDir-to-tmpdir): add new node.js 18 migration codemod`
-- `fix(esm-migration): correct type checking in ESM migration`
-- `docs(codemod-usage): improve usage examples`
+- ``feat(DEP0022): migrate `tmpDir` to `tmpdir` ``
+- ``fix(`tmpDir-to-tmpdir`): correct type checking in …``
+- ``docs(`tmpDir-to-tmpdir`): correct usage example``
+- `docs(CONTRIBUTING): improve good test examples`
 
 ## Pull Request Process