Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix Linear release stamping across divergent stable histories (#4494)

Andrew Mikofalvy9fab1905d9cb
diff --git a/.github/scripts/derive-release-stamp.mjs b/.github/scripts/derive-release-stamp.mjs
index 1c365b34c..03866c72c 100644
--- a/.github/scripts/derive-release-stamp.mjs
+++ b/.github/scripts/derive-release-stamp.mjs
@@ -20,9 +20,7 @@ export function parseReleaseTag(rawTag) {
const stable = STABLE_TAG_RE.exec(tag);
if (stable) return { channel: 'stable', version: tag.slice(1), name: tag };
- throw new Error(
- `unrecognized release tag '${tag}' (expected vX.Y.Z or vX.Y.Z-beta.N)`,
- );
+ throw new Error(`unrecognized release tag '${tag}' (expected vX.Y.Z or vX.Y.Z-beta.N)`);
}
function stableKey(rawTag) {
@@ -51,17 +49,21 @@ export function previousStableTag({ tags, tag }) {
return best ? best.tag : null;
}
-export function deriveReleaseStamp({ tag, tags, describePreviousTag }) {
+export function deriveReleaseStamp({ tag, tags, describePreviousTag, resolveStableBaseRef }) {
const parsed = parseReleaseTag(tag);
- const baseRef =
+ let baseRef =
parsed.channel === 'beta'
? (describePreviousTag(parsed.name) ?? null)
: previousStableTag({ tags, tag: parsed.name });
+ if (parsed.channel === 'stable' && baseRef) {
+ baseRef = resolveStableBaseRef(baseRef, parsed.name);
+ }
return { ...parsed, baseRef: baseRef || null };
}
-function runGit(args) {
+function runGit(args, { allowNoMergeBase = false } = {}) {
const res = spawnSync('git', args, { encoding: 'utf8' });
+ if (allowNoMergeBase && res.status === 1 && !res.stdout && !res.stderr) return '';
if (res.status !== 0) {
throw new Error(
`git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,
@@ -70,6 +72,31 @@ function runGit(args) {
return String(res.stdout || '');
}
+function realResolveStableBaseRef(previousTag, tag) {
+ const bases = runGit(['merge-base', '--all', previousTag, tag], { allowNoMergeBase: true })
+ .trim()
+ .split('\n')
+ .filter(Boolean);
+ if (bases.length === 0) {
+ throw new Error(
+ `no common ancestor between ${previousTag} and ${tag}; refusing to guess a scan range`,
+ );
+ }
+ if (bases.length !== 1) {
+ throw new Error(
+ `expected one merge base between ${previousTag} and ${tag}, got ${bases.length}`,
+ );
+ }
+ const previousCommit = runGit(['rev-parse', `${previousTag}^{commit}`]).trim();
+ if (bases[0] === previousCommit) return previousTag;
+ const tagCommit = runGit(['rev-parse', `${tag}^{commit}`]).trim();
+ if (bases[0] === tagCommit) {
+ throw new Error(`${tag} is behind its previous stable ${previousTag}; refusing an empty scan`);
+ }
+ log(`::notice::Using merge base ${bases[0]} because ${previousTag} is not an ancestor of ${tag}`);
+ return bases[0];
+}
+
function realTags() {
return runGit(['tag', '--list', 'v*'])
.split('\n')
@@ -107,6 +134,7 @@ function main() {
tag: process.argv[2],
tags: realTags(),
describePreviousTag: realDescribePreviousTag,
+ resolveStableBaseRef: realResolveStableBaseRef,
});
} catch (err) {
console.error(`::error::derive-release-stamp: ${err.message}`);
diff --git a/.github/scripts/derive-release-stamp.test.mjs b/.github/scripts/derive-release-stamp.test.mjs
index 4d6b1a3ff..5d28d1382 100644
--- a/.github/scripts/derive-release-stamp.test.mjs
+++ b/.github/scripts/derive-release-stamp.test.mjs
@@ -1,4 +1,11 @@
-import { describe, expect, test } from 'vitest';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, test } from 'vitest';
+import { parse } from 'yaml';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
import {
deriveReleaseStamp,
formatOutputLines,
@@ -129,6 +136,7 @@ describe('deriveReleaseStamp', () => {
tag: 'v0.46.0',
tags: TAGS,
describePreviousTag: () => 'v0.46.0-beta.3',
+ resolveStableBaseRef: (previous) => previous,
});
expect(stamp.baseRef).toBe('v0.45.5');
expect(stamp.channel).toBe('stable');
@@ -208,3 +216,253 @@ describe('regressions from the measured mis-stamps', () => {
expect(previousStableTag({ tags: TAGS, tag: 'v0.45.1' })).toBe('v0.45.0');
});
});
+
+const tempRepos = [];
+afterEach(() => {
+ for (const dir of tempRepos.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function makeReleaseRepo() {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-release-stamp-'));
+ tempRepos.push(dir);
+ const env = gitCleanEnv();
+ const git = (...args) =>
+ execFileSync(
+ 'git',
+ [
+ '-c',
+ 'user.name=Test',
+ '-c',
+ '-c',
+ 'commit.gpgsign=false',
+ '-c',
+ 'tag.gpgsign=false',
+ ...args,
+ ],
+ { cwd: dir, encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] },
+ ).trim();
+ git('init', '--quiet', '--initial-branch=main');
+ const commit = (subject) => {
+ git('commit', '--quiet', '--allow-empty', '-m', subject);
+ return git('rev-parse', 'HEAD');
+ };
+ const run = (tag) =>
+ spawnSync(
+ process.execPath,
+ [fileURLToPath(new URL('./derive-release-stamp.mjs', import.meta.url)), tag],
+ { cwd: dir, encoding: 'utf8', env: { ...env, GITHUB_OUTPUT: join(dir, 'output') } },
+ );
+ return { dir, git, commit, run };
+}
+
+describe('release scan bounds with real Git histories', () => {
+ test('v0.71.8 uses the common ancestor of a divergent v0.71.7 without widening the scan', () => {
+ const { dir, git, commit, run } = makeReleaseRepo();
+ commit('PRD-1000: already shipped');
+ git('tag', 'v0.70.0');
+ const common = commit('PRD-1001: also already shipped');
+ git('switch', '-c', 'previous-stable');
+ commit('PRD-1002: only in the previous release');
+ git('tag', 'v0.71.7');
+ git('switch', 'main');
+ const first = commit('PRD-1003: first new fix');
+ git('tag', 'v0.71.8-beta.1');
+ const second = commit('PRD-1004: second new fix');
+ git('tag', 'v0.71.8');
+ const result = run('v0.71.8');
+ expect(result.status, result.stderr).toBe(0);
+ expect(result.stderr).toContain(`::notice::Using merge base ${common}`);
+ expect(result.stderr).toContain('v0.71.7 is not an ancestor of v0.71.8');
+ const stamp = JSON.parse(result.stdout);
+ expect(stamp).toEqual({
+ channel: 'stable',
+ version: '0.71.8',
+ name: 'v0.71.8',
+ baseRef: common,
+ });
+ expect(git('merge-base', '--is-ancestor', stamp.baseRef, 'HEAD')).toBe('');
+ expect(git('rev-list', `${stamp.baseRef}..HEAD`).split('\n')).toEqual([second, first]);
+ expect(git('rev-list', `${stamp.baseRef}..HEAD`)).toBe(git('rev-list', 'v0.71.7..HEAD'));
+ expect(readFileSync(join(dir, 'output'), 'utf8')).toContain(`base_ref=${common}\n`);
+ });
+
+ test.each([false, true])(
+ 'retains an ancestral stable tag (annotated: %s) and includes the whole beta cycle',
+ (annotated) => {
+ const { git, commit, run } = makeReleaseRepo();
+ commit('previous stable');
+ git('tag', ...(annotated ? ['-a', 'v0.71.7', '-m', 'previous stable'] : ['v0.71.7']));
+ const first = commit('first beta fix');
+ git('tag', 'v0.71.8-beta.1');
+ const second = commit('second beta fix');
+ git('tag', 'v0.71.8');
+ const result = run('v0.71.8');
+ expect(result.status, result.stderr).toBe(0);
+ const { baseRef } = JSON.parse(result.stdout);
+ expect(baseRef).toBe('v0.71.7');
+ expect(git('rev-list', `${baseRef}..HEAD`).split('\n')).toEqual([second, first]);
+ },
+ );
+
+ test('keeps a beta bounded by its preceding reachable tag', () => {
+ const { git, commit, run } = makeReleaseRepo();
+ commit('stable');
+ git('tag', 'v0.71.7');
+ commit('first beta');
+ git('tag', 'v0.71.8-beta.1');
+ commit('second beta');
+ git('tag', 'v0.71.8-beta.2');
+ const result = run('v0.71.8-beta.2');
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout).baseRef).toBe('v0.71.8-beta.1');
+ });
+
+ test('leaves the first stable release unbounded', () => {
+ const { git, commit, run } = makeReleaseRepo();
+ commit('first release');
+ git('tag', 'v0.1.0');
+ const result = run('v0.1.0');
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout).baseRef).toBeNull();
+ });
+
+ test.each(['missing', 'broken'])(
+ 'restores both stamping scripts and their imports over %s historical scripts',
+ (history) => {
+ const { dir, git, commit } = makeReleaseRepo();
+ const common = commit('common');
+ git('switch', '-c', 'previous-stable');
+ commit('previous stable');
+ git('tag', 'v0.71.7');
+ git('switch', 'main');
+ mkdirSync(join(dir, '.github/scripts'), { recursive: true });
+ const helperPath = join(dir, '.github/scripts/derive-release-stamp.mjs');
+ if (history === 'broken') {
+ writeFileSync(helperPath, 'process.exit(99);\n');
+ writeFileSync(
+ join(dir, '.github/scripts/stamp-by-containment.mjs'),
+ "import { missing } from './resolve-shipped-version.mjs';\n",
+ );
+ writeFileSync(
+ join(dir, '.github/scripts/resolve-shipped-version.mjs'),
+ 'export const renamed = true;\n',
+ );
+ }
+ git('add', '.');
+ commit('historical release with broken stamping helper');
+ git('tag', 'v0.71.8');
+ git('switch', '-c', 'workflow-revision');
+ cpSync(fileURLToPath(new URL('.', import.meta.url)), join(dir, '.github/scripts'), {
+ recursive: true,
+ });
+ git('add', '.');
+ const workflowSha = commit('fixed stamping scripts');
+ const env = {
+ ...gitCleanEnv(),
+ RELEASE_TAG: 'v0.71.8',
+ GITHUB_OUTPUT: join(dir, 'output'),
+ LINEAR_API_KEY: '',
+ CROSS_REPO_TOKEN: '',
+ };
+ const workflow = readFileSync(
+ new URL('../workflows/linear-release.yml', import.meta.url),
+ 'utf8',
+ );
+ const runStep = (name, revision = workflowSha) => {
+ const step = parse(workflow).jobs.stamp.steps.find((step) => step.name === name);
+ return spawnSync('bash', ['-eu', '-c', step.run], {
+ cwd: dir,
+ env: { ...env, WORKFLOW_SHA: revision },
+ encoding: 'utf8',
+ });
+ };
+ git('checkout', '--detach', 'v0.71.8');
+ const broken = runStep('Correct the stable stamp by containment');
+ expect(broken.status).not.toBe(0);
+ const failedRestore = runStep(
+ 'Restore stamping scripts from workflow revision',
+ '0'.repeat(40),
+ );
+ expect(failedRestore.status).not.toBe(0);
+ expect(git('status', '--porcelain')).toBe('');
+ expect(runStep('Correct the stable stamp by containment').status).not.toBe(0);
+ const restore = runStep('Restore stamping scripts from workflow revision');
+ expect(restore.status, restore.stderr).toBe(0);
+ const result = runStep('Derive channel, version, and scan range');
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout).baseRef).toBe(common);
+ expect(git('rev-parse', 'HEAD')).toBe(git('rev-parse', 'v0.71.8'));
+ expect(readFileSync(join(dir, 'output'), 'utf8')).toContain(`base_ref=${common}\n`);
+ const containment = runStep('Correct the stable stamp by containment');
+ expect(containment.status, containment.stderr).toBe(0);
+ expect(containment.stderr).toContain('LINEAR_API_KEY');
+ },
+ );
+
+ test('refuses a stable selected behind its predecessor', () => {
+ const { dir, git, commit, run } = makeReleaseRepo();
+ commit('earlier build');
+ git('tag', 'v0.71.8');
+ commit('previous stable has additional commits');
+ git('tag', 'v0.71.7');
+ git('checkout', '--detach', 'v0.71.8');
+ const result = run('v0.71.8');
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain('v0.71.8 is behind its previous stable v0.71.7');
+ expect(() => readFileSync(join(dir, 'output'))).toThrow();
+ });
+
+ test('allows stable versions pointing at the same commit', () => {
+ const { git, commit, run } = makeReleaseRepo();
+ commit('shared release commit');
+ git('tag', 'v0.71.7');
+ git('tag', 'v0.71.8');
+ const result = run('v0.71.8');
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout).baseRef).toBe('v0.71.7');
+ });
+
+ test('preserves Git errors instead of misclassifying invalid objects as unrelated histories', () => {
+ const { dir, git, commit, run } = makeReleaseRepo();
+ commit('release');
+ git('tag', 'v0.71.8');
+ git('tag', 'v0.71.7', git('rev-parse', 'HEAD^{tree}'));
+ const result = run('v0.71.8');
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain('git merge-base --all v0.71.7 v0.71.8 failed');
+ expect(result.stderr).not.toContain('no common ancestor');
+ expect(() => readFileSync(join(dir, 'output'))).toThrow();
+ });
+
+ test('refuses unrelated release histories instead of silently scanning everything', () => {
+ const { dir, git, commit, run } = makeReleaseRepo();
+ commit('previous stable');
+ git('tag', 'v0.71.7');
+ git('switch', '--orphan', 'unrelated');
+ commit('new stable');
+ git('tag', 'v0.71.8');
+ const result = run('v0.71.8');
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain('no common ancestor between v0.71.7 and v0.71.8');
+ expect(() => readFileSync(join(dir, 'output'))).toThrow();
+ });
+
+ test('refuses criss-cross histories rather than arbitrarily selecting a common ancestor', () => {
+ const { dir, git, commit, run } = makeReleaseRepo();
+ const root = commit('root');
+ const tree = git('rev-parse', 'HEAD^{tree}');
+ const a = git('commit-tree', tree, '-p', root, '-m', 'a');
+ const b = git('commit-tree', tree, '-p', root, '-m', 'b');
+ const previous = git('commit-tree', tree, '-p', a, '-p', b, '-m', 'previous release');
+ const current = git('commit-tree', tree, '-p', b, '-p', a, '-m', 'current release');
+ git('tag', 'v0.71.7', previous);
+ git('tag', 'v0.71.8', current);
+ git('checkout', '--detach', current);
+ expect(git('merge-base', '--all', previous, current).split('\n').sort()).toEqual([a, b].sort());
+ const result = run('v0.71.8');
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain('expected one merge base between v0.71.7 and v0.71.8, got 2');
+ expect(() => readFileSync(join(dir, 'output'))).toThrow();
+ });
+});
diff --git a/.github/scripts/linear-release-shape.test.mjs b/.github/scripts/linear-release-shape.test.mjs
index a766dae10..26660595b 100644
--- a/.github/scripts/linear-release-shape.test.mjs
+++ b/.github/scripts/linear-release-shape.test.mjs
@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, test } from 'vitest';
+import { parse } from 'yaml';
const WORKFLOWS = join(dirname(fileURLToPath(import.meta.url)), '..', 'workflows');
const workflow = readFileSync(join(WORKFLOWS, 'linear-release.yml'), 'utf8');
@@ -44,6 +45,26 @@ const UNDELIVERABLE_POST_ONLY_WARNS =
/if ! curl[\s\S]*?; then\n\s+echo "::warning::Linear stamping failure alert failed to POST\."\n\s+fi/;
describe('linear release stamping workflow', () => {
+ test('restores workflow revision scripts after checking out historical release code', () => {
+ const labels = stepLabels(workflow);
+ const expected = [
+ 'Checkout at the release tag',
+ 'Restore stamping scripts from workflow revision',
+ 'Derive channel, version, and scan range',
+ ];
+ expect(labels.filter((label) => expected.includes(label))).toEqual(expected);
+ const restore = Object.values(parse(workflow).jobs)
+ .flatMap((job) => job.steps)
+ .find((step) => step.name === 'Restore stamping scripts from workflow revision');
+ expect(restore.env.WORKFLOW_SHA).toBe('${{ github.workflow_sha }}');
+ expect(restore.run).toBe(
+ 'git restore --source "$WORKFLOW_SHA" --worktree .github/scripts/',
+ );
+ expect(workflow).toContain(
+ 'run: node .github/scripts/derive-release-stamp.mjs "${RELEASE_TAG}"',
+ );
+ });
+
test('a failed stamp pages the releases channel', () => {
const alert = alertBlock(workflow);
expect(alert).toMatch(/^ {8}if: failure\(\) \|\| cancelled\(\)$/m);
@@ -56,6 +77,9 @@ describe('linear release stamping workflow', () => {
expect(text).toContain('${TAG}');
expect(text).toContain('${RUN_URL}');
expect(text).toContain('${OUTCOME}');
+ expect(text).toContain('dispatch linear-release.yml fresh on main');
+ expect(text).toContain('release_tag=${TAG}');
+ expect(text).toContain('re-running the old run keeps its old code');
expect(alert).toMatch(OUTCOME_BRANCH);
expect(alert).toContain('JOB_STATUS: ${{ job.status }}');
diff --git a/.github/workflows/linear-release.yml b/.github/workflows/linear-release.yml
index 0217ea20c..a2ca000f3 100644
--- a/.github/workflows/linear-release.yml
+++ b/.github/workflows/linear-release.yml
@@ -54,24 +54,6 @@ name: Linear Release
# resolved keeps whatever it had. Ships in dry-run until the STAMP_MODE repo
# variable is set to `live`.
#
-# Running this workflow by hand against any stable tag re-runs that pass over
-# the whole pipeline, which is also how a backfill of historical stamps is
-# performed — the pass is not scoped to the dispatching tag.
-#
-# COMMIT SCAN RANGE
-# The lower bound depends on the channel, because the two releases answer
-# different questions:
-# beta -> previous tag of any kind, so the beta holds what is NEW in it
-# and a ticket lands on the beta it FIRST shipped in.
-# stable -> previous STABLE tag, skipping betas. A promotion batches every
-# changeset since the last stable, so stopping at the most recent
-# beta would miss every ticket from earlier betas in the cycle.
-# sync is idempotent, so a re-run simply re-affirms an already-attached set.
-#
-# Both derivations live in .github/scripts/derive-release-stamp.mjs with a
-# colocated test suite. They are NOT inline shell: this workflow shipped a
-# wrong-version defect that untested `${VAR%%...}` expansion made invisible.
-#
# ONE-TIME SETUP
# 1. A Linear SCHEDULED pipeline "OpenKnowledge" (team Product) with exactly
# one custom started stage named `Beta`. Shipped-to-production maps to the
@@ -90,24 +72,6 @@ name: Linear Release
# After adding the secret, dry-run against a recent tag before trusting it:
# run this workflow via workflow_dispatch with a real release_tag and read
# the CLI output. (linear-release-action also supports dry_run for the CLI.)
-#
-# SAFETY
-# Fully decoupled from the release/publish path — a failure here can never
-# break a release. The job no-ops cleanly when LINEAR_ACCESS_KEY is absent.
-# That decoupling cuts both ways, so the final step pages the releases channel
-# on failure: nothing downstream notices when stamping stops, and without the
-# page a broken run looks exactly like a healthy one from outside.
-#
-# What that page does NOT cover, so it is not mistaken for full coverage:
-# a dispatch that never fires produces no run to attach a guard to, and any
-# check for that would have to live with the producers (release.yml for beta,
-# promote-stable.yml for stable). Nor does it cover the containment pass
-# exiting 0 having reconciled nothing: with LINEAR_API_KEY unset it logs a
-# notice and returns, and a ticket whose PR attachments all point outside the
-# private monorepo is filtered out before any API call is made. Credential
-# faults that DO reach the API throw rather than reading as an answer, so
-# those go red and this page fires. stamp-by-containment.mjs is the authority
-# on which paths exit 0; do not restate its branches here.
on:
repository_dispatch:
@@ -157,6 +121,12 @@ jobs:
fetch-depth: 0
fetch-tags: true
+ - name: Restore stamping scripts from workflow revision
+ if: env.HAS_KEY == 'true'
+ env:
+ WORKFLOW_SHA: ${{ github.workflow_sha }}
+ run: git restore --source "$WORKFLOW_SHA" --worktree .github/scripts/
+
- name: Set up Node
if: env.HAS_KEY == 'true'
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -291,7 +261,7 @@ jobs:
else
OUTCOME="failed"
fi
- TEXT="Linear release stamping ${OUTCOME} for ${TAG}${CHANNEL:+ (${CHANNEL})}. The release itself is unaffected; Linear is now out of sync with what shipped. Re-running is safe, though on a stable tag it re-verifies every stable release's stamps rather than just this one. ${RUN_URL}"
+ TEXT="Linear release stamping ${OUTCOME} for ${TAG}${CHANNEL:+ (${CHANNEL})}. The release itself is unaffected; Linear is now out of sync with what shipped. Re-running is safe for transient failures. After a stamping-code fix reaches main, dispatch linear-release.yml fresh on main with release_tag=${TAG}; re-running the old run keeps its old code. Stable dispatches re-verify every stable release's stamps, not just this one. ${RUN_URL}"
{
echo "## Linear stamping ${OUTCOME}"
echo "Tag: \`${TAG}\`"