Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Scope reporter write-back to the release it was handed (PRD-7667) (#2981)

Andrew Mikofalvy25d2e7a8d293
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjs
index 3abf8b9ea..bbf35e9a3 100644
--- a/.github/scripts/write-back.mjs
+++ b/.github/scripts/write-back.mjs
@@ -166,6 +166,61 @@ function compareSemver(a, b) {
return 0;
}
+export const DEFAULT_RELEASE_LOOKBACK = 3;
+
+/** `v0.36.0` and `0.36.0` both mean the same release; anything else means none. */
+function normalizeVersion(raw) {
+ const trimmed = String(raw ?? '').trim().replace(/^v/, '');
+ return /^\d+\.\d+\.\d+$/.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Decide which shipped versions a given run is allowed to speak about.
+ *
+ * The release being processed is the ceiling: a fix that lands in a later
+ * version has not reached anybody yet, so telling its reporter would be a lie.
+ *
+ * The floor is deliberately a few releases further back rather than the release
+ * itself. A run that never happened — a workflow outage, or simply the stretch
+ * before any of this was armed — would otherwise strand those reporters
+ * permanently, because the next release only ever considers its own version and
+ * nothing ever revisits the gap. Widening the floor is safe because the
+ * absent-marker check, not the width of this window, is what prevents a second
+ * reply: the window is bounded by "has not been told yet".
+ *
+ * Without a window every completed fix in history looks eligible, which on a
+ * first armed run means messaging the entire back catalogue at once.
+ */
+export function makeReleaseWindow({
+ releaseTag,
+ stableTags = [],
+ lookback = DEFAULT_RELEASE_LOOKBACK,
+}) {
+ const release = normalizeVersion(releaseTag);
+ if (!release) {
+ throw new Error(
+ `RELEASE_TAG must be a bare stable tag such as v0.36.0 (got ${JSON.stringify(releaseTag)}). ` +
+ 'Refusing to run: with no release to scope against, every shipped fix in history is a candidate.',
+ );
+ }
+
+ const known = [...new Set(stableTags.map(normalizeVersion).filter(Boolean))].sort(compareSemver);
+ const atOrBelow = known.filter((v) => compareSemver(v, release) <= 0);
+ // Keep the release plus `lookback` older ones; the entry just below that
+ // block is the exclusive floor. Too little history to reach back that far
+ // means everything at or below the release stays in.
+ const floorIndex = atOrBelow.length - (lookback + 1) - 1;
+ const floor = floorIndex >= 0 ? atOrBelow[floorIndex] : null;
+
+ return (version) => {
+ const shipped = normalizeVersion(version);
+ if (!shipped) return 'unversioned';
+ if (compareSemver(shipped, release) > 0) return 'not-yet-shipped';
+ if (floor && compareSemver(shipped, floor) <= 0) return 'shipped-earlier';
+ return 'in-window';
+ };
+}
+
/**
* Walk every candidate and decide, for each, whether to reply and where.
*
@@ -191,9 +246,17 @@ export async function runWriteBack({
readChangesetProse,
postReply,
recordNotification,
+ classifyRelease,
live = false,
log = () => {},
}) {
+ // No default. A missing window is not "notify about everything", it is a
+ // caller that forgot to scope the run, and the difference between those two
+ // readings is the entire back catalogue.
+ if (typeof classifyRelease !== 'function') {
+ throw new Error('runWriteBack requires classifyRelease; see makeReleaseWindow.');
+ }
+
const posted = [];
const skipped = [];
const skip = (identifier, reason) => skipped.push({ identifier, reason });
@@ -228,6 +291,15 @@ export async function runWriteBack({
continue;
}
+ // Scope to the release this run is about. Skips here are the ordinary bulk
+ // of a run rather than a fault, so they are recorded per candidate and
+ // summarised at the end instead of annotated one line at a time.
+ const placement = classifyRelease(gate.version);
+ if (placement !== 'in-window') {
+ skip(candidate.identifier, placement);
+ continue;
+ }
+
if (origins.length === 0) {
if (unrepliable.length > 0) {
log(
@@ -517,6 +589,8 @@ async function main() {
log('::notice::write-back: running in dry-run mode (set WRITE_BACK_MODE=live to arm reporter replies).');
}
+ const releaseTag = process.env.RELEASE_TAG;
+
const stableTags = realStableTags();
const versionFor = (node) =>
deriveVersionForFixRefs({
@@ -528,10 +602,17 @@ async function main() {
log,
});
+ const classifyRelease = makeReleaseWindow({ releaseTag, stableTags });
+ log(
+ `::notice::write-back: scoped to ${releaseTag} and the ${DEFAULT_RELEASE_LOOKBACK} stable releases before it; ` +
+ 'anything shipped earlier is left alone.',
+ );
+
const result = await runWriteBack({
listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {} }),
listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId } }),
versionFor,
+ classifyRelease,
readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),
postReply: realPostReply,
recordNotification: async ({ issueId, url, title }) => {
diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjs
index 725eec82f..d27c1e7fa 100644
--- a/.github/scripts/write-back.test.mjs
+++ b/.github/scripts/write-back.test.mjs
@@ -2,7 +2,9 @@ import { readFileSync } from 'node:fs';
import { describe, expect, test } from 'vitest';
import {
CANDIDATE_QUERY,
+ DEFAULT_RELEASE_LOOKBACK,
deriveVersionForFixRefs,
+ makeReleaseWindow,
notificationMarkerUrl,
parseChangeset,
runWriteBack,
@@ -41,6 +43,9 @@ function harness(overrides = {}) {
readChangesetProse: async () => CHANGESET,
postReply: async (origin, text) => writes.push({ kind: 'post', origin: origin.url, text }),
recordNotification: async (marker) => writes.push({ kind: 'mark', url: marker.url }),
+ // Every candidate in these fixtures ships in v0.36.0; the window tests
+ // below drive the scoping itself.
+ classifyRelease: makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: STABLE_TAGS }),
log: (m) => logs.push(m),
...overrides,
};
@@ -377,3 +382,113 @@ describe('workflow shape', () => {
expect(workflow).toContain('LINEAR_API_KEY');
});
});
+
+describe('release window', () => {
+ // A longer history than the lookback, so "outside the window" is reachable.
+ const TAGS = ['v0.34.0', 'v0.35.0', 'v0.35.1', 'v0.35.2', 'v0.36.0', 'v0.37.0'];
+ const windowFor = (releaseTag, lookback) =>
+ makeReleaseWindow({ releaseTag, stableTags: TAGS, lookback });
+
+ test('the release being processed is in window', () => {
+ expect(windowFor('v0.36.0')('0.36.0')).toBe('in-window');
+ });
+
+ test('a version above the release has not reached anyone yet', () => {
+ expect(windowFor('v0.36.0')('0.37.0')).toBe('not-yet-shipped');
+ });
+
+ test('the lookback keeps recent releases reachable so a missed run self-heals', () => {
+ const classify = windowFor('v0.36.0', 3);
+ // v0.36.0 plus the three before it.
+ for (const v of ['0.36.0', '0.35.2', '0.35.1', '0.35.0']) {
+ expect(classify(v)).toBe('in-window');
+ }
+ });
+
+ test('anything older than the lookback is left alone', () => {
+ expect(windowFor('v0.36.0', 3)('0.34.0')).toBe('shipped-earlier');
+ });
+
+ test('a narrower lookback excludes more of the history', () => {
+ const classify = windowFor('v0.36.0', 1);
+ expect(classify('0.35.2')).toBe('in-window');
+ expect(classify('0.35.1')).toBe('shipped-earlier');
+ });
+
+ test('a zero lookback degenerates to the exact release and nothing else', () => {
+ const classify = windowFor('v0.36.0', 0);
+ expect(classify('0.36.0')).toBe('in-window');
+ expect(classify('0.35.2')).toBe('shipped-earlier');
+ });
+
+ test('too little history to reach back keeps everything at or below the release', () => {
+ // Fewer known tags than the lookback wants leaves no floor at all, so the
+ // ceiling is the only bound. Pinned because it is a distinct branch from
+ // the one every other case here exercises.
+ const classify = makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: ['v0.36.0'] });
+ expect(classify('0.36.0')).toBe('in-window');
+ expect(classify('0.35.0')).toBe('in-window');
+ expect(classify('0.37.0')).toBe('not-yet-shipped');
+ });
+
+ test('the v prefix is accepted on both sides', () => {
+ expect(windowFor('0.36.0')('v0.36.0')).toBe('in-window');
+ });
+
+ test('an underivable version is reported as such rather than silently admitted', () => {
+ expect(windowFor('v0.36.0')(null)).toBe('unversioned');
+ });
+
+ test('a missing or malformed release tag refuses rather than admitting all of history', () => {
+ for (const bad of [undefined, '', ' ', 'v0.36.0-beta.1', 'latest']) {
+ expect(() => makeReleaseWindow({ releaseTag: bad, stableTags: TAGS })).toThrow(/RELEASE_TAG/);
+ }
+ });
+
+ test('the default lookback is three', () => {
+ expect(DEFAULT_RELEASE_LOOKBACK).toBe(3);
+ });
+});
+
+describe('release window applied to a run', () => {
+ // The fixture candidate ships in v0.36.0 throughout.
+ test('a candidate that shipped before the window is skipped, not replied to', async () => {
+ const h = harness({
+ live: true,
+ classifyRelease: makeReleaseWindow({
+ releaseTag: 'v0.41.0',
+ stableTags: ['v0.36.0', 'v0.38.0', 'v0.39.0', 'v0.40.0', 'v0.41.0'],
+ }),
+ });
+ const result = await h.run();
+ expect(result.skipped).toContainEqual({ identifier: 'PRD-7539', reason: 'shipped-earlier' });
+ expect(h.writes).toHaveLength(0);
+ });
+
+ test('a candidate whose fix is not in this release yet is skipped, not replied to', async () => {
+ const h = harness({
+ live: true,
+ classifyRelease: makeReleaseWindow({
+ releaseTag: 'v0.35.0',
+ stableTags: ['v0.35.0', 'v0.36.0'],
+ }),
+ });
+ const result = await h.run();
+ expect(result.skipped).toContainEqual({ identifier: 'PRD-7539', reason: 'not-yet-shipped' });
+ expect(h.writes).toHaveLength(0);
+ });
+
+ test('a candidate inside the window still gets its reply', async () => {
+ const h = harness({
+ live: true,
+ classifyRelease: makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: STABLE_TAGS }),
+ });
+ await h.run();
+ expect(h.writes.filter((w) => w.kind === 'post')).toHaveLength(1);
+ });
+
+ test('runWriteBack refuses to run unscoped', async () => {
+ const h = harness({ live: true, classifyRelease: undefined });
+ await expect(h.run()).rejects.toThrow(/classifyRelease/);
+ });
+});