Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mjsindex 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.mjsindex 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',+ '[email protected]',+ '-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.mjsindex 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.ymlindex 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: 0fetch-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 Nodeif: env.HAS_KEY == 'true'uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0@@ -291,7 +261,7 @@ jobs:elseOUTCOME="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}\`"