From 54ca83651fe974616acc83004d933bad4e743889 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 27 Oct 2026 23:35:23 -0400 Subject: [PATCH] fix(release): prepare release candidates explicitly --- .github/workflows/release-please.yml | 11 +- docs/releasing.md | 50 +++++- scripts/release-candidate.test.mjs | 251 +++++++++++++++++++++++++++ 3 files changed, 304 insertions(+), 8 deletions(-) create mode 100644 scripts/release-candidate.test.mjs diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 807d116..8e9ab72 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -35,6 +35,9 @@ jobs: config-file: release-please-config.json manifest-file: .release-please-manifest.json target-branch: main + # Only an explicit preparation may create or refresh the candidate. + # Pushes still turn merged release PRs into their exact tags and drafts. + skip-github-pull-request: ${{ github.event_name != 'workflow_dispatch' }} release-pr-status: needs: version @@ -76,9 +79,11 @@ jobs: } appendFileSync(process.env.GITHUB_STEP_SUMMARY, [ '## Release PR validation', '', ...rows, '', - 'After the intended main-branch changes are complete, review the current release PR head.', - 'A maintainer can close and reopen the PR to trigger native CI and metadata-only title validation; if it is behind main, Update branch also triggers them.', - 'Review any Approve workflows to run prompt. Confirm All checks and Conventional Commit PR title pass in the PR checks before merging.', + 'This explicit preparation may change the release PR head. Main pushes will not refresh it again.', + 'Give the release PR a short merge window: keep main unchanged during final preparation, native validation and squash merge. Development can continue on branches.', + 'After preparation, a maintainer must close and reopen the PR to trigger native CI and metadata-only title validation. Approving bot-created CI alone does not trigger the title workflow.', + 'Review any Approve workflows to run prompt. Confirm All checks and Conventional Commit PR title pass on the current head before merging.', + 'If main advances first, prepare again and review the resulting version, notes and head; strict up-to-date checks still apply. After merging, publication stays on the exact tag while main advances.', 'workflow_dispatch checks do not satisfy PR rulesets. This summary does not approve workflows, and workflow approval does not merge or publish.', 'Final publication still requires the separate owner approval in the release environment.', '', ].join('\n')); diff --git a/docs/releasing.md b/docs/releasing.md index 47e96dd..5f52e41 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -165,9 +165,9 @@ rechecking boundary and composition behavior, not assuming it is unchanged. ## Automated path -1. A merge to `main` runs `release-please.yml`. Its metadata-only job creates or updates the release PR; it does not check out project code. -2. The workflow reports the generated **release PR and current head** in its job summary without launching duplicate checks. GitHub queues `GITHUB_TOKEN`-generated `pull_request` CI for workflow-execution approval, but does not trigger the metadata-only `pull_request_target` title workflow. Moreover, dispatched workflow checks [do not satisfy PR rulesets](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks#checks-from-some-workflow-jobs-are-not-evaluated), even when green on that head. After the intended main-branch changes are complete, review the finalized release PR; a maintainer can **close and reopen** it to trigger native CI and title validation, or **Update branch** if it is behind `main`. Review any **Approve workflows to run** prompt and confirm **All checks** and **Conventional Commit PR title** pass in the PR checks. Recheck the head after any update; earlier-head or manual-dispatch success is not admission evidence. Workflow execution approval neither merges the PR nor publishes a release. -3. Review and squash merge the release PR. Release Please creates a **draft release** and, with `force-tag-creation`, creates its `vX.Y.Z` tag while it is still a draft. +1. Explicitly run **Release Please** on `main` (`gh workflow run release-please.yml --repo Lunary-Lab/mp3-frame-analyzer --ref main`) to prepare or refresh a release PR. This metadata-only job does not check out project code. Ordinary `main` pushes set `skip-github-pull-request: true`: they process merged release PRs but cannot create or rewrite an open candidate. Dispatch is an intentional refresh, not a read-only preview; it can also recover tags/drafts for already merged release PRs. +2. The workflow reports the generated **release PR and current head** in its job summary. After preparation, a maintainer must **close and reopen** the PR to trigger native CI and metadata-only title validation. GitHub queues `GITHUB_TOKEN`-generated `pull_request` CI for workflow-execution approval, but still suppresses `pull_request_target`; approving that CI alone does not start the title workflow. Review any **Approve workflows to run** prompt and confirm **All checks** and **Conventional Commit PR title** pass on the current head. Earlier-head success and dispatched checks [do not satisfy PR rulesets](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks#checks-from-some-workflow-jobs-are-not-evaluated). Workflow execution approval neither merges the PR nor publishes a release. +3. Review and squash merge the release PR during the merge window below. The resulting `main` push creates a **draft release** and, with `force-tag-creation`, its `vX.Y.Z` tag at the release PR's merge commit. A later `main` commit does not move this release source. 4. The workflow dispatches `publish-release.yml` **at that exact tag**, passing its full commit SHA. Preflight requires a matching draft, a matching tag commit already reachable from `main`, and `GITHUB_SHA` equal to the declared source commit. Dispatching from `main` is rejected. 5. The reusable, read-only CI validates that commit. It checks Node 24 and 26, npm compatibility, formatting, lint, both TypeScript compilers, coverage, tooling, mutation testing, fuzzing, dependency audits, static analysis, secrets, and measured memory/HTTP behavior. The Node 24 release lane packages the existing compiled output and tests the unpacked artifact; the publisher never rebuilds it. 6. Native notes preparation independently verifies the same release range. The candidate job seals the tested runtime and both notes views, with immutable input identities and checksums, into one artifact. Build provenance attests every sealed file. @@ -175,6 +175,46 @@ rechecking boundary and composition behavior, not assuming it is unchanged. The version verifier requires agreement between `package.json`, both lockfile root versions, the release manifest, and the supplied release tag. In CI, the recorded source commit must equal the checked-out Git HEAD. Tag-based invocation also keeps the standard attestation's workflow commit aligned with the actual build source. +### Finishing a candidate while development continues + +Freezing automatic proposal updates stops Release Please from invalidating a +reviewed head after every merge. It does **not** freeze a historical source tree +or remove strict up-to-date checks. With the merge queue disabled, another merge +to `main` can still require bringing the candidate current and validating it again. +No workflow-only change can guarantee admission while `main` changes continuously +under that rule. + +Give the release PR a short merge window: pause other merges into `main`, run the +explicit preparation once, trigger native checks as above, then squash merge it +when both required checks pass. Work on development branches can continue during +this window. Resume ordinary merges immediately after the release PR merges; +the exact-tag publication checks and owner approval can finish independently. +If `main` advances before the release PR merges, prepare again and review the +new version, changelog and head. Bringing a candidate current includes newer +code; merely updating its branch can leave the prepared notes or version stale, +especially after a breaking change. Every intentional refresh needs fresh +current-head checks. + +The pinned action independently calls release creation and PR preparation +([action source](https://github.com/googleapis/release-please-action/blob/45996ed1f6d02564a971a2fa1b5860e934307cf7/src/index.ts#L136-L152)). +Release Please 17.6.0 derives the release SHA from the merged PR +([release construction](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/strategies/base.ts#L713-L718)) +and uses it for the tag and draft +([GitHub adapter](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/github-api.ts#L667-L695)). +GitHub documents the remaining +[strict-check requirement](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-status-checks-to-pass-before-merging) +and [bot-event behavior](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request). + +For comparison, the action's own +[release workflow](https://github.com/googleapis/release-please-action/blob/45996ed1f6d02564a971a2fa1b5860e934307cf7/.github/workflows/release-please.yaml) +separates release creation from proposal updates but runs both on every main +push; separation alone does not freeze a candidate. Node.js instead explicitly +[prepares from a release staging branch](https://github.com/nodejs/node/blob/ec7a28f2e074f0ea16ecd4d2a3511b334fa4b0de/.github/workflows/create-release-proposal.yml) +and [targets its release line](https://github.com/nodejs/node/blob/ec7a28f2e074f0ea16ecd4d2a3511b334fa4b0de/doc/contributing/releases.md#L585-L613), +isolating release integration from `main` with a separate branch/backport process. +This repository keeps its existing main-branch release path and uses the bounded +merge window instead. + ## Published files | File | Contents | @@ -273,8 +313,8 @@ dependencies, upload an MP3, and stop the server with `SIGTERM`. ## Recover from a failed release -- **Release PR validation failed or required checks are absent:** fix any source defect in an ordinary PR and finish the intended main-branch batch before validating the release PR again. Review its current head, then close and reopen it as a maintainer to trigger both native CI and metadata-only title validation; **Update branch** is another option when it is behind `main`. Review any workflow-execution approval prompt and verify both required checks in the PR, not a separate manual dispatch. A GitHub App installation token can automate eligible events without recurring prompts, but configuring one is optional and requires separate credential/permission approval; it is not required for this maintainer path. Publication still revalidates the exact tag and waits for separate final owner approval. -- **Publication failed after the draft and tag were created:** a retry runs the workflows and source from the tag, so changes merged to `main` cannot repair it. Retry the draft as shown below for transient failures, such as a runner or network error. If the tagged source or its workflows are defective, leave the draft unpublished, merge the fix, and let Release Please propose the next version. Never move or recreate a release tag. +- **Release PR validation failed or required checks are absent:** fix any source defect in an ordinary PR, then use the [merge window](#finishing-a-candidate-while-development-continues) to explicitly prepare the candidate again. Review its current version, notes and head, then close and reopen it as a maintainer to trigger both native CI and metadata-only title validation. Review any workflow-execution approval prompt and verify both required checks in the PR, not a separate manual dispatch. CI approval alone does not start the title workflow. A GitHub App installation token can automate eligible events without recurring prompts, but configuring one is optional and requires separate credential/permission approval; it is not required for this maintainer path. Publication still revalidates the exact tag and waits for separate final owner approval. +- **Publication failed after the draft and tag were created:** a retry runs the workflows and source from the tag, so changes merged to `main` cannot repair it. Retry the draft as shown below for transient failures, such as a runner or network error. If the tagged source or its workflows are defective, leave the draft unpublished, merge the fix, and explicitly run Release Please on `main` to prepare the next version. Never move or recreate a release tag. - **A published release is defective:** published releases are immutable. Merge a correction and release a new version. ## Retry an unpublished draft diff --git a/scripts/release-candidate.test.mjs b/scripts/release-candidate.test.mjs new file mode 100644 index 0000000..0bf9913 --- /dev/null +++ b/scripts/release-candidate.test.mjs @@ -0,0 +1,251 @@ +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { test } from 'node:test'; +import { runInNewContext } from 'node:vm'; +import { parse } from 'yaml'; + +const read = (path) => readFile(new URL(`../${path}`, import.meta.url), 'utf8'); +const workflow = async (name) => parse(await read(`.github/workflows/${name}.yml`)); +const release = await workflow('release-please'); +const publisher = await workflow('publish-release'); +const ci = await workflow('ci'); +const title = await workflow('pr-title'); + +// These expressions use only string/boolean comparisons, shared by Actions and JS. +// This tests workflow routing, not a replacement implementation of Release Please. +function evaluate(expression, values) { + return runInNewContext(expression.replace(/^\$\{\{\s*|\s*\}\}$/g, ''), values, { + timeout: 100, + }); +} + +function runInline(shell, env, execFileSync = () => assert.fail('Unexpected subprocess')) { + const source = shell.match(/^node --input-type=module <<'JS'\n([\s\S]+)\nJS\s*$/)?.[1]; + assert.ok(source, 'Expected one inline Node script'); + const imports = source.match(/^import .+;$/gm) ?? []; + for (const line of imports) { + assert.ok( + [ + "import assert from 'node:assert/strict';", + "import { execFileSync } from 'node:child_process';", + ].includes(line), + `Unexpected dependency: ${line}`, + ); + } + // Execute the actual trusted workflow script with an isolated environment and + // an inert subprocess boundary. No shell, network or filesystem mutation runs. + const execute = new Function( + 'assert', + 'execFileSync', + 'process', + source.replace(/^import .+;\n/gm, ''), + ); + execute(assert, execFileSync, { env }); +} + +test('main pushes cannot rewrite proposals; only explicit preparation enables the native PR writer', () => { + assert.deepEqual(Object.keys(release.on).sort(), ['push', 'workflow_dispatch']); + assert.deepEqual(release.on.push, { branches: ['main'] }); + const version = release.jobs.version; + assert.equal(version.steps.length, 1, 'Keep a single native release writer without custom state'); + const action = version.steps[0]; + assert.equal( + action.uses, + 'googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7', + ); + assert.equal(action.id, 'release'); + assert.equal(action.if, undefined); + assert.equal(action.with['target-branch'], 'main'); + for (const [event, skipProposal] of [ + ['push', true], + ['workflow_dispatch', false], + ]) { + const github = { event_name: event, ref: 'refs/heads/main' }; + assert.equal(evaluate(version.if, { github }), true); + assert.equal(evaluate(action.with['skip-github-pull-request'], { github }), skipProposal); + github.ref = 'refs/heads/feature'; + assert.equal(evaluate(version.if, { github }), false); + } + assert.deepEqual(release.concurrency, { + group: 'release-please-main', + 'cancel-in-progress': false, + }); +}); + +test('merged release processing stays enabled independently of proposal preparation', async () => { + const action = release.jobs.version.steps[0]; + assert.equal(action.with['skip-github-release'] ?? false, false); + const config = JSON.parse(await read(action.with['config-file'])); + assert.equal(config.packages['.'].draft, true); + assert.equal(config.packages['.']['force-tag-creation'], true); + assert.equal(release.jobs.version.outputs.tag, '${{ steps.release.outputs.tag_name }}'); + assert.equal(release.jobs.version.outputs.sha, '${{ steps.release.outputs.sha }}'); + assert.equal(release.jobs.release.needs, 'version'); + assert.equal(release.jobs.release.if, "needs.version.outputs.release_created == 'true'"); + assert.equal( + evaluate(release.jobs.release.if, { + needs: { version: { outputs: { release_created: 'true', prs_created: 'false' } } }, + }), + true, + ); +}); + +test('the actual release handoff uses the merged release SHA and tag even after main advances', () => { + const step = release.jobs.release.steps[0]; + assert.equal(step.env.RELEASE_TAG, '${{ needs.version.outputs.tag }}'); + assert.equal(step.env.RELEASE_SHA, '${{ needs.version.outputs.sha }}'); + const env = { + GH_REPO: 'example/project', + RELEASE_TAG: 'v2.3.0', + RELEASE_SHA: 'a'.repeat(40), + GITHUB_SHA: 'b'.repeat(40), + GITHUB_REF: 'refs/heads/main', + }; + const calls = []; + runInline(step.run, env, (...args) => calls.push(args)); + assert.deepEqual(calls, [ + [ + 'gh', + [ + 'workflow', + 'run', + 'publish-release.yml', + '--repo', + 'example/project', + '--ref', + 'v2.3.0', + '-f', + 'tag=v2.3.0', + '-f', + `sha=${env.RELEASE_SHA}`, + ], + { stdio: 'inherit' }, + ], + ]); + for (const change of [{ RELEASE_TAG: 'main' }, { RELEASE_SHA: 'short' }]) { + assert.throws(() => runInline(step.run, { ...env, ...change })); + } +}); + +test('publication retains exact-source verification and the separate owner environment gate', () => { + assert.deepEqual(Object.keys(publisher.on), ['workflow_dispatch']); + assert.equal(publisher.jobs.verify.with.ref, '${{ inputs.sha }}'); + assert.equal(publisher.jobs.verify.with.release_tag, '${{ inputs.tag }}'); + assert.equal(publisher.jobs.notes.with.sha, '${{ inputs.sha }}'); + assert.equal(publisher.jobs.publish.environment.name, 'release'); + assert.deepEqual(publisher.jobs.publish.needs, ['preflight', 'candidate', 'provenance']); + const needs = Object.fromEntries( + publisher.jobs.publish.needs.map((name) => [name, { result: 'success' }]), + ); + const values = { github: { run_attempt: 1 }, needs, always: () => true }; + assert.equal(evaluate(publisher.jobs.publish.if, values), true); + for (const dependency of Object.values(needs)) { + dependency.result = 'skipped'; + assert.equal(evaluate(publisher.jobs.publish.if, values), false); + dependency.result = 'success'; + } +}); + +test('the actual publication guard requires exactly one approved decision from the configured owner', () => { + const shell = publisher.jobs.publish.steps.find((step) => + step.run?.includes('function requireOwnerApproval()'), + )?.run; + const source = shell?.match( + /function requireOwnerApproval\(\) \{[\s\S]*?\n\}\nrequireOwnerApproval\(\);/, + )?.[0]; + assert.ok(source, 'Expected the publication guard and its immediate invocation'); + const execute = new Function('assert', 'e', 'api', 'execFileSync', source); + const owner = publisher.env.RELEASE_APPROVER_ID; + const e = { + GH_REPO: 'example/project', + GITHUB_RUN_ID: '123', + ENVIRONMENT_ID: '8', + APPROVER_ID: owner, + RELEASE_APPROVER_ID: owner, + }; + const environment = { + id: 8, + can_admins_bypass: false, + deployment_branch_policy: { protected_branches: false, custom_branch_policies: true }, + protection_rules: [ + { + type: 'required_reviewers', + prevent_self_review: false, + reviewers: [{ type: 'User', reviewer: { id: Number(owner), type: 'User' } }], + }, + ], + }; + const approval = { + state: 'approved', + user: { id: Number(owner), type: 'User' }, + environments: [{ id: 8 }], + }; + const run = (reviews) => + execute( + assert, + e, + (path) => { + if (path === 'environments/release') return environment; + assert.equal(path, 'actions/runs/123/approvals'); + return reviews; + }, + (command, args) => { + assert.equal(command, 'gh'); + assert.deepEqual(args, [ + 'api', + '--method', + 'GET', + '--paginate', + '--slurp', + 'repos/example/project/environments/release/deployment-branch-policies?per_page=100', + ]); + return JSON.stringify([{ branch_policies: [{ name: 'v*', type: 'tag' }] }]); + }, + ); + assert.doesNotThrow(() => run([approval])); + for (const reviews of [ + [], + [approval, approval], + [{ ...approval, user: { id: 999, type: 'User' } }], + [{ ...approval, state: 'rejected' }], + [{ ...approval, environments: [{ id: 9 }] }], + ]) + assert.throws(() => run(reviews), assert.AssertionError); +}); + +test('native required PR checks stay unfiltered and metadata-only title validation cannot be skipped', () => { + assert.equal(ci.on.pull_request, null); + assert.deepEqual(title.on.pull_request_target.types, [ + 'opened', + 'edited', + 'reopened', + 'synchronize', + ]); + assert.deepEqual(title.permissions, { 'pull-requests': 'read' }); + assert.equal(title.jobs.title.name, 'Conventional Commit PR title'); + assert.equal( + evaluate(title.jobs.title.steps[0].if, { github: { event_name: 'pull_request_target' } }), + true, + ); + for (const property of ['if', 'needs', 'strategy', 'uses']) + assert.equal(title.jobs.title[property], undefined); + assert.doesNotMatch(JSON.stringify(title), /checkout@/); + const aggregate = ci.jobs['all-checks']; + assert.equal(aggregate.name, 'All checks'); + assert.equal(aggregate.if, 'always()'); + assert.deepEqual( + aggregate.needs.toSorted(), + Object.keys(ci.jobs) + .filter((name) => name !== 'all-checks') + .sort(), + ); + const results = Object.fromEntries(aggregate.needs.map((name) => [name, { result: 'success' }])); + const run = () => runInline(aggregate.steps[0].run, { RESULTS: JSON.stringify(results) }); + assert.doesNotThrow(run); + for (const result of ['skipped', 'cancelled', 'failure']) { + results.mutation.result = result; + assert.throws(run, /Required jobs did not pass: mutation/); + } + delete results.mutation; + assert.throws(run, /Incomplete or unexpected job inventory/); +});