Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): write back on both channels, drop the Bug gate (PRD-8280) (#3844)
Andrew Mikofalvyaee7fc4c50e0
diff --git a/.github/scripts/resolve-shipped-version.mjs b/.github/scripts/resolve-shipped-version.mjsindex 0017abfea..34d971cd3 100644--- a/.github/scripts/resolve-shipped-version.mjs+++ b/.github/scripts/resolve-shipped-version.mjs@@ -54,6 +54,11 @@ import { appendFileSync } from 'node:fs';import { pathToFileURL } from 'node:url';const STABLE_TAG_RE = /^v(\d+)\.(\d+)\.(\d+)$/;+// A prerelease tag of the beta cadence: `v0.59.0-beta.3`. Deliberately its own+// pattern rather than an optional group on STABLE_TAG_RE, so every stable-only+// call site keeps refusing prereleases by construction. The beta channel has to+// ask for them; it must not be reachable by an accidental widening.+const BETA_TAG_RE = /^v(\d+)\.(\d+)\.(\d+)-beta\.(\d+)$/;const FULL_SHA_RE = /^[0-9a-f]{40}$/i;// Copybara emits the trailer on its own line. Matched case-insensitively on// the key and anchored to a line start so a trailer quoted inside a prose body@@ -118,6 +123,64 @@ export function parseFixRef(raw, { defaultRepo = DEFAULT_PRIVATE_REPO } = {}) {);}+/**+ * Sort key for a release tag, or null when the tag is neither a stable nor a+ * beta of the cadence this repo cuts.+ *+ * The fourth component carries semver's prerelease precedence: every+ * `v0.59.0-beta.N` ranks BELOW the `v0.59.0` that supersedes it. That ordering+ * is the whole reason the beta channel can answer "the earliest build carrying+ * this fix" with the beta rather than the stable that followed it weeks later.+ *+ * The same precedence rule is spelled out once more, over version strings rather+ * than tags, as `releaseVersionKey` in `write-back-gate.mjs`. That file is+ * deliberately IO-free and imports nothing from here, so the two cannot share an+ * implementation; a change to the shape of this repo's release tags has to land+ * in both.+ */+function releaseTagKey(raw) {+ const line = String(raw).trim();+ const stable = STABLE_TAG_RE.exec(line);+ if (stable) {+ return { tag: stable[0], key: [Number(stable[1]), Number(stable[2]), Number(stable[3]), 1, 0] };+ }+ const beta = BETA_TAG_RE.exec(line);+ if (beta) {+ return {+ tag: beta[0],+ key: [Number(beta[1]), Number(beta[2]), Number(beta[3]), 0, Number(beta[4])],+ };+ }+ return null;+}++function byReleaseKeyAscending(a, b) {+ for (let i = 0; i < a.key.length; i += 1) {+ if (a.key[i] !== b.key[i]) return a.key[i] - b.key[i];+ }+ return 0;+}++/**+ * Sort every release tag this repo cuts — stables and betas together —+ * ascending, dropping non-conforming refs.+ *+ * Kept separate from the stable-only sorter rather than folded into it behind a+ * flag. The two answer different questions, and the failure mode of conflating+ * them is asymmetric: a stable channel that accidentally saw a prerelease would+ * tell a reporter their fix is out when only a beta carries it, which is the one+ * thing this whole path exists not to do.+ */+export function sortReleaseTagsAscending(rawTags) {+ const parsed = [];+ for (const line of rawTags) {+ const entry = releaseTagKey(line);+ if (entry) parsed.push(entry);+ }+ parsed.sort(byReleaseKeyAscending);+ return parsed.map((p) => p.tag);+}+/** Sort `vX.Y.Z` tags ascending by numeric semver, dropping non-conforming refs. */export function sortStableTagsAscending(rawTags) {const parsed = [];@@ -153,12 +216,24 @@ export function firstContainingStableTag({ sortedStableTags, sha, contains }) {* findMirroredCommits(privateSha) -> [{ sha, message }] (candidates; may over-match)* contains(tag, sha) -> boolean (sha is in tag's history)*+ * `channel` selects which tags count as a build a reporter could install:+ * `stable` (the default) considers bare `vX.Y.Z` only, `beta` considers every+ * tag of the cadence so the answer can be the prerelease the fix first reached.+ * `stableTags` is the raw `git tag --list v*` output either way — betas are+ * present in it already, and the channel is what decides whether they count.+ ** Returns one of:* { shipped: true, privateSha, mirroredSha, mirroredShas, tag, version }* { shipped: false, reason: 'not-mirrored', privateSha, mirroredShas: [] }- * { shipped: false, reason: 'not-in-any-stable', privateSha, mirroredShas }+ * { shipped: false, reason: 'not-in-any-stable' | 'not-in-any-release', privateSha, mirroredShas }*/-export function resolveShippedVersion({ privateSha, stableTags, findMirroredCommits, contains }) {+export function resolveShippedVersion({+ privateSha,+ stableTags,+ findMirroredCommits,+ contains,+ channel = 'stable',+}) {if (!FULL_SHA_RE.test(String(privateSha ?? ''))) {throw new Error(`privateSha must be a full 40-character commit SHA, got '${privateSha}'`);}@@ -177,7 +252,8 @@ export function resolveShippedVersion({ privateSha, stableTags, findMirroredCommreturn { shipped: false, reason: 'not-mirrored', privateSha: wanted, mirroredShas: [] };}- const sorted = sortStableTagsAscending(stableTags);+ const sorted =+ channel === 'beta' ? sortReleaseTagsAscending(stableTags) : sortStableTagsAscending(stableTags);const rank = new Map(sorted.map((tag, i) => [tag, i]));// A fix can exist at more than one mirrored SHA: a point release cherry-picks@@ -195,7 +271,8 @@ export function resolveShippedVersion({ privateSha, stableTags, findMirroredComm}}if (best === null) {- return { shipped: false, reason: 'not-in-any-stable', privateSha: wanted, mirroredShas };+ const reason = channel === 'beta' ? 'not-in-any-release' : 'not-in-any-stable';+ return { shipped: false, reason, privateSha: wanted, mirroredShas };}return {@@ -218,8 +295,31 @@ function runGit(args) {return String(res.stdout || '');}-export function realStableTags() {- return runGit(['tag', '--list', 'v*', '--sort=version:refname']).split('\n');+/**+ * Split `git tag --list` output into tags.+ *+ * Pure, and separated from the git call so the one property that matters here+ * can be tested: prereleases come back. A caller that wants only stables asks+ * the sorter for them, because the sorter is where the channel is known.+ */+export function parseTagLines(raw) {+ return String(raw ?? '')+ .split('\n')+ .map((line) => line.trim())+ .filter(Boolean);+}++/**+ * Every release tag this repo has cut, prereleases INCLUDED.+ *+ * Named for what it returns. It was `realStableTags`, and a second, private copy+ * of it in `write-back.mjs` quietly filtered to bare `vX.Y.Z` to live up to that+ * name — which silently emptied the beta channel, since no prerelease ever+ * reached the channel-aware resolver. One reader, honestly named, and the+ * filtering left to the sorter that knows which channel is asking.+ */+export function realReleaseTags() {+ return parseTagLines(runGit(['tag', '--list', 'v*', '--sort=version:refname']));}// Record separator between commits and a unit separator between the SHA and@@ -300,7 +400,7 @@ function main() {const privateSha = resolvePrivateSha(fixRef, { resolvePrMergeSha: realResolvePrMergeSha });result = resolveShippedVersion({privateSha,- stableTags: realStableTags(),+ stableTags: realReleaseTags(),findMirroredCommits: realFindMirroredCommits,contains: realContains,});diff --git a/.github/scripts/resolve-shipped-version.test.mjs b/.github/scripts/resolve-shipped-version.test.mjsindex a28fc6a64..5a9ce5cbd 100644--- a/.github/scripts/resolve-shipped-version.test.mjs+++ b/.github/scripts/resolve-shipped-version.test.mjs@@ -3,8 +3,10 @@ import {firstContainingStableTag,parseFixRef,parseGitOriginRevIds,+ parseTagLines,resolvePrivateSha,resolveShippedVersion,+ sortReleaseTagsAscending,sortStableTagsAscending,} from './resolve-shipped-version.mjs';@@ -344,3 +346,123 @@ describe('resolvePrivateSha', () => {).toThrow(/not merged/);});});++describe('release tags across both channels', () => {+ const MIXED = ['v0.36.0', 'v0.35.0-beta.10', 'v0.35.0', 'v0.35.0-beta.2', 'not-a-tag', 'v0.35.6'];++ test('a beta sorts below the stable it becomes, and betas order numerically', () => {+ // String ordering would put beta.10 before beta.2 and leave the stable+ // adjacent to its own prereleases in whatever order they were listed.+ expect(sortReleaseTagsAscending(MIXED)).toEqual([+ 'v0.35.0-beta.2',+ 'v0.35.0-beta.10',+ 'v0.35.0',+ 'v0.35.6',+ 'v0.36.0',+ ]);+ });++ test('the stable sorter still refuses every prerelease', () => {+ expect(sortStableTagsAscending(MIXED)).toEqual(['v0.35.0', 'v0.35.6', 'v0.36.0']);+ });+});++describe('resolving against a channel', () => {+ const PRIVATE = 'a'.repeat(40);+ const MIRRORED = 'b'.repeat(40);+ const TAGS = ['v0.35.0', 'v0.36.0-beta.0', 'v0.36.0-beta.1', 'v0.36.0'];+ const findMirrored = (sha) =>+ sha === PRIVATE ? [{ sha: MIRRORED, message: `subject\n\nGitOrigin-RevId: ${PRIVATE}\n` }] : [];+ // The fix landed in the first beta of the 0.36 cycle and rode it to stable.+ const contains = (tag, sha) =>+ sha === MIRRORED && ['v0.36.0-beta.0', 'v0.36.0-beta.1', 'v0.36.0'].includes(tag);++ test('the beta channel answers with the first build of any kind that carried it', () => {+ const result = resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: TAGS,+ findMirroredCommits: findMirrored,+ contains,+ channel: 'beta',+ });+ expect(result).toMatchObject({+ shipped: true,+ tag: 'v0.36.0-beta.0',+ version: '0.36.0-beta.0',+ });+ });++ test('the stable channel ignores the betas entirely and answers with the stable', () => {+ const result = resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: TAGS,+ findMirroredCommits: findMirrored,+ contains,+ });+ expect(result).toMatchObject({ shipped: true, tag: 'v0.36.0', version: '0.36.0' });+ });++ test('a fix that reached a beta but no stable is unshipped on the stable channel and shipped on the beta one', () => {+ const betaOnly = (tag, sha) => sha === MIRRORED && tag === 'v0.36.0-beta.1';+ expect(+ resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: TAGS,+ findMirroredCommits: findMirrored,+ contains: betaOnly,+ }),+ ).toMatchObject({ shipped: false, reason: 'not-in-any-stable' });+ expect(+ resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: TAGS,+ findMirroredCommits: findMirrored,+ contains: betaOnly,+ channel: 'beta',+ }),+ ).toMatchObject({ shipped: true, version: '0.36.0-beta.1' });+ });++ test('a fix in no tag at all reports the channel it failed against', () => {+ expect(+ resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: TAGS,+ findMirroredCommits: findMirrored,+ contains: () => false,+ channel: 'beta',+ }),+ ).toMatchObject({ shipped: false, reason: 'not-in-any-release' });+ });+});+++describe('the tag boundary', () => {+ test('prereleases survive it, because the channel decides what counts and not this', () => {+ // The beta channel went dead on a reader that filtered to bare vX.Y.Z here.+ // Filtering belongs to the sorter, which knows which channel is asking.+ expect(parseTagLines('v0.36.0\nv0.37.0-beta.1\n\n v0.37.0 \n')).toEqual([+ 'v0.36.0',+ 'v0.37.0-beta.1',+ 'v0.37.0',+ ]);+ });++ test('a fix that only a stable contains resolves to that stable even on the beta channel', () => {+ // The precondition behind `stable-covers-it`: a point-release cherry-pick+ // has no beta to point anyone at, so the beta run must see a stable-shaped+ // version and stand down rather than invent one.+ const PRIVATE = 'a'.repeat(40);+ const MIRRORED = 'b'.repeat(40);+ expect(+ resolveShippedVersion({+ privateSha: PRIVATE,+ stableTags: ['v0.35.0', 'v0.36.0-beta.0', 'v0.36.0'],+ findMirroredCommits: (sha) =>+ sha === PRIVATE ? [{ sha: MIRRORED, message: `GitOrigin-RevId: ${PRIVATE}` }] : [],+ contains: (tag, sha) => sha === MIRRORED && tag === 'v0.36.0',+ channel: 'beta',+ }),+ ).toMatchObject({ shipped: true, tag: 'v0.36.0', version: '0.36.0' });+ });+});diff --git a/.github/scripts/write-back-gate.mjs b/.github/scripts/write-back-gate.mjsindex 0f0ff57ae..cc3994dc3 100644--- a/.github/scripts/write-back-gate.mjs+++ b/.github/scripts/write-back-gate.mjs@@ -1,5 +1,5 @@/**- * The decisions behind telling a bug reporter their fix shipped: which of a+ * The decisions behind telling a reporter their fix is out: which of a* ticket's attachments is a place a human can be replied to, and whether* everything that descended from their report has actually gone out.*@@ -40,7 +40,10 @@ const DISCORD_THREAD_RE =const SLACK_ARCHIVE_RE = /^https?:\/\/[^/]*\.slack\.com\/archives\//i;const LINEAR_UPLOAD_RE = /^https?:\/\/uploads\.linear\.app\//i;-const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;+// Accepts both channels' version strings: `0.59.1` and `0.59.0-beta.3`. The+// optional prerelease group is captured so ordering can honour semver+// precedence, where a beta ranks below the stable of the same X.Y.Z.+const RELEASE_VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/;const RELEASES_URL = 'https://github.com/inkeep/open-knowledge/releases';// Discord caps a message at 2000 characters. Bounding the quoted prose leaves@@ -52,14 +55,24 @@ const MAX_PROSE_CHARS = 1200;* What a single attachment URL is, for write-back purposes.** { kind: 'repliable-origin', channel: 'github-issue' | 'discord-thread', ... }- * { kind: 'unrepliable-origin', channel: 'slack-archive' | 'linear-upload' }+ * { kind: 'unrepliable-origin', channel: 'slack-archive' }+ * { kind: 'evidence', channel: 'linear-upload' }* { kind: 'fix-reference', channel: 'pull-request' | 'commit' }* { kind: 'unknown' }** `unrepliable-origin` exists as its own answer rather than collapsing into- * `unknown` so the caller can say WHY it skipped. A Slack archive link and a- * diagnostic bundle both name a real report; there is simply nowhere in them to- * post a reply, and that is worth a warning rather than silence.+ * `unknown` so the caller can say WHY it skipped: a Slack archive link names a+ * real report, in a thread someone is waiting in, that this workflow has no way+ * to post into. That is worth a warning rather than silence.+ *+ * An uploaded file is NOT that, and calling it one was a mistake worth naming.+ * `uploads.linear.app` is any file dragged onto any ticket: a screenshot, a+ * diagnostic zip, a log. Nobody is waiting inside it. While the enumeration was+ * narrowed to Bug tickets the difference rarely showed, because a bundle on a+ * bug ticket did imply a report. Workspace-wide it is simply an attachment, and+ * treating it as an origin would both keep every ticket carrying a screenshot on+ * the expensive path and produce a warning saying its "only origin" cannot be+ * replied to, when the ticket never had an origin at all.*/export function classifyAttachment(rawUrl) {const url = String(rawUrl ?? '').trim();@@ -113,16 +126,16 @@ export function classifyAttachment(rawUrl) {return { kind: 'unrepliable-origin', channel: 'slack-archive', url };}if (LINEAR_UPLOAD_RE.test(url)) {- return { kind: 'unrepliable-origin', channel: 'linear-upload', url };+ return { kind: 'evidence', channel: 'linear-upload', url };}return { kind: 'unknown', url };}/**- * Split a ticket's attachments into the three buckets the write-back needs.- * Returns { origins, unrepliable, fixReferences } with the classification- * objects, in attachment order.+ * Split a ticket's attachments into the buckets the write-back needs.+ * Returns { origins, unrepliable, evidence, fixReferences } with the+ * classification objects, in attachment order.** `fixReferences` keeps pull requests ahead of commits: a pull request resolves* to a merge commit whose mirrored copy is what tag containment walks, while a@@ -132,6 +145,7 @@ export function classifyAttachment(rawUrl) {export function partitionAttachments(attachmentUrls = []) {const origins = [];const unrepliable = [];+ const evidence = [];const pulls = [];const commits = [];@@ -139,27 +153,66 @@ export function partitionAttachments(attachmentUrls = []) {const classified = classifyAttachment(raw);if (classified.kind === 'repliable-origin') origins.push(classified);else if (classified.kind === 'unrepliable-origin') unrepliable.push(classified);+ else if (classified.kind === 'evidence') evidence.push(classified);else if (classified.kind === 'fix-reference') {(classified.channel === 'pull-request' ? pulls : commits).push(classified);}}- return { origins, unrepliable, fixReferences: [...pulls, ...commits] };+ return { origins, unrepliable, evidence, fixReferences: [...pulls, ...commits] };+}++/**+ * Whether this workflow can actually post to an origin, from the repo it runs in.+ *+ * A Discord thread is reachable through the bot regardless of repo. A GitHub+ * issue is only reachable when it lives in THIS repo: the reply is posted with+ * the job's own `GITHUB_TOKEN`, which has no standing anywhere else.+ *+ * This matters far more now that the candidate query no longer filters by+ * label. The backlog spans several products, and a completed ticket over in+ * another one routinely carries an issue origin in that product's repo. Without+ * this check every one of them would be attempted, 403, and be collected as a+ * failure, turning a correctly-behaving run red on tickets it was never+ * supposed to speak about.+ */+export function isOriginRepliableFrom(origin, selfRepo) {+ if (origin?.channel === 'discord-thread') return true;+ if (origin?.channel !== 'github-issue') return false;+ const self = String(selfRepo ?? '')+ .trim()+ .toLowerCase();+ if (!self) return false;+ return self === `${origin.owner}/${origin.repo}`.toLowerCase();}/** Numeric semver ordering. String comparison puts v0.9.0 above v0.36.0. */export function compareVersions(a, b) {- const pa = SEMVER_RE.exec(String(a ?? '').trim());- const pb = SEMVER_RE.exec(String(b ?? '').trim());- if (!pa) throw new Error(`not a version: '${a}'`);- if (!pb) throw new Error(`not a version: '${b}'`);- for (let i = 1; i <= 3; i += 1) {- const diff = Number(pa[i]) - Number(pb[i]);- if (diff !== 0) return diff;+ const ka = releaseVersionKey(a);+ const kb = releaseVersionKey(b);+ if (!ka) throw new Error(`not a version: '${a}'`);+ if (!kb) throw new Error(`not a version: '${b}'`);+ for (let i = 0; i < ka.length; i += 1) {+ if (ka[i] !== kb[i]) return ka[i] - kb[i];}return 0;}+/**+ * Ordering key for a version string, or null if it is not one.+ *+ * The fourth component is 1 for a stable and 0 for a beta, so `0.59.0-beta.9`+ * sorts below `0.59.0` exactly as semver requires. Without it a plain+ * three-part compare calls them equal, and `highestVersion` over a fan-in+ * spanning both channels would pick whichever happened to come first.+ */+function releaseVersionKey(raw) {+ const m = RELEASE_VERSION_RE.exec(String(raw ?? '').trim());+ if (!m) return null;+ const isStable = m[4] === undefined;+ return [Number(m[1]), Number(m[2]), Number(m[3]), isStable ? 1 : 0, isStable ? 0 : Number(m[4])];+}+/** Highest of a non-empty version list, normalized without the leading `v`. */export function highestVersion(versions) {let best = null;@@ -294,13 +347,22 @@ export function evaluateFanIn({ ticket, descendants = [], resolveVersion, log =* empty changeset is the one case: a blank or version-only reply reads as a* claim with no content behind it, so the caller warns and posts nothing.*/-export function composeReply({ changeset = {}, version, originChannel, coverage = [] }) {+export function composeReply({+ changeset = {},+ version,+ originChannel,+ coverage = [],+ channel = 'stable',+}) {const normalizedVersion = String(version ?? '').trim().replace(/^v/, '');- if (!SEMVER_RE.test(normalizedVersion)) {+ if (!RELEASE_VERSION_RE.test(normalizedVersion)) {throw new Error(`composeReply needs a derived version, got '${version}'`);}+ if (channel !== 'stable' && channel !== 'beta') {+ throw new Error(`composeReply needs a channel of 'stable' or 'beta', got '${channel}'`);+ }const body = String(changeset.body ?? '').trim();const title = String(changeset.title ?? '').trim();@@ -310,17 +372,13 @@ export function composeReply({ changeset = {}, version, originChannel, coverageconst trimmedProse =prose.length > MAX_PROSE_CHARS ? `${prose.slice(0, MAX_PROSE_CHARS).trimEnd()}...` : prose;- const lines = [- `This shipped in Open Knowledge v${normalizedVersion}. Thanks for the report.`,- '',- trimmedProse,- ];+ const lines = [openingLine(channel, normalizedVersion), '', trimmedProse];if (coverage.length > 0) {lines.push('', `Covers ${[...coverage].sort().join(', ')}.`);}- lines.push('', updateInstruction(originChannel));+ lines.push('', updateInstruction(originChannel, channel, normalizedVersion));return lines.join('\n');}@@ -335,9 +393,43 @@ export function composeReply({ changeset = {}, version, originChannel, coverage* renders an inline link, while a bare URL on Discord expands into an embed* card unless it is wrapped in angle brackets.*/-function updateInstruction(originChannel) {+function updateInstruction(originChannel, channel = 'stable', version = '') {+ // A beta is not on the update channel the desktop app follows, so "update to+ // the latest" would send a reporter to a build that does not carry the fix.+ // The beta build has to be downloaded deliberately, and the wording says so.+ const action =+ channel === 'beta'+ ? `To try it ahead of that, download the v${version} beta from`+ : 'To pick it up, update to the latest desktop app from';+ const tail = channel === 'beta' ? ' once its installers have finished uploading' : '';if (originChannel === 'discord-thread') {- return `To pick it up, update to the latest desktop app from <${RELEASES_URL}>.`;+ return `${action} <${RELEASES_URL}>${tail}.`;+ }+ return `${action} [the releases page](${RELEASES_URL})${tail}.`;+}++/**+ * The claim the reply opens with, which is the part a reporter reads.+ *+ * The two channels make genuinely different claims and must not share wording.+ * A stable reply says the fix is out, full stop. A beta reply has to carry three+ * things at once: it is fixed, the build carrying it is a beta rather than the+ * channel their app follows, and a second message is coming when the stable+ * ships. That last one is a promise the stable leg keeps, and it is what makes+ * the two messages read as a sequence rather than as the same news sent twice.+ */+function openingLine(channel, version) {+ if (channel === 'beta') {+ // Deliberately not "available now". The dispatch this runs off fires when the+ // release is still a DRAFT, minutes to an hour before its installers finish+ // uploading, so a reporter sent to the releases page at that moment finds+ // nothing there. Saying it is going out, and that the build appears when its+ // installers do, is true at every point in that window.+ return (+ `This is fixed, and it is going out now on the Open Knowledge beta channel as v${version}. ` ++ 'Thanks for the report. It will reach the stable channel in an upcoming release, ' ++ 'and we will follow up here when it does.'+ );}- return `To pick it up, update to the latest desktop app from [the releases page](${RELEASES_URL}).`;+ return `This shipped in Open Knowledge v${version}. Thanks for the report.`;}diff --git a/.github/scripts/write-back-gate.test.mjs b/.github/scripts/write-back-gate.test.mjsindex fcb299f17..3ad4e9d4c 100644--- a/.github/scripts/write-back-gate.test.mjs+++ b/.github/scripts/write-back-gate.test.mjs@@ -4,6 +4,7 @@ import {compareVersions,composeReply,evaluateFanIn,+ isOriginRepliableFrom,highestVersion,partitionAttachments,} from './write-back-gate.mjs';@@ -46,12 +47,24 @@ describe('attachment classification', () => {expect(c.channel).toBe('slack-archive');});- test('a Linear diagnostic bundle is an origin with nowhere to reply', () => {+ test('a Linear upload is evidence on the ticket, not a place anyone is waiting', () => {+ // Any file dragged onto any ticket lands here: a screenshot, a log, a+ // diagnostic zip. Reading one as an origin kept every such ticket on the+ // expensive path and produced a warning about an "only origin" that could+ // not be replied to, on tickets that never had an origin.const c = classifyAttachment(LINEAR_UPLOAD);- expect(c.kind).toBe('unrepliable-origin');+ expect(c.kind).toBe('evidence');expect(c.channel).toBe('linear-upload');});+ test('evidence is neither an origin nor a fix reference when the buckets are split', () => {+ const parts = partitionAttachments([LINEAR_UPLOAD, GH_ISSUE, GH_PULL]);+ expect(parts.evidence.map((e) => e.url)).toEqual([LINEAR_UPLOAD]);+ expect(parts.origins.map((o) => o.url)).toEqual([GH_ISSUE]);+ expect(parts.unrepliable).toEqual([]);+ expect(parts.fixReferences.map((f) => f.url)).toEqual([GH_PULL]);+ });+test('a GitHub pull request is a fix reference and never an origin', () => {const c = classifyAttachment(GH_PULL);expect(c.kind).toBe('fix-reference');@@ -372,3 +385,106 @@ describe('reply composition', () => {expect(text).not.toContain('Dana');});});++describe('origin remit', () => {+ const issue = (owner, repo) => ({ channel: 'github-issue', owner, repo });++ test('an issue in this repo is repliable and one anywhere else is not', () => {+ expect(isOriginRepliableFrom(issue('inkeep', 'open-knowledge'), 'inkeep/open-knowledge')).toBe(+ true,+ );+ expect(isOriginRepliableFrom(issue('inkeep', 'agents'), 'inkeep/open-knowledge')).toBe(false);+ expect(isOriginRepliableFrom(issue('someone', 'fork'), 'inkeep/open-knowledge')).toBe(false);+ });++ test('the comparison ignores case, because GitHub slugs are not case sensitive', () => {+ expect(isOriginRepliableFrom(issue('Inkeep', 'Open-Knowledge'), 'inkeep/open-knowledge')).toBe(+ true,+ );+ });++ test('a Discord thread is repliable regardless of repo, and an unknown repo makes nothing repliable', () => {+ expect(isOriginRepliableFrom({ channel: 'discord-thread', threadId: '1' }, '')).toBe(true);+ expect(isOriginRepliableFrom(issue('inkeep', 'open-knowledge'), '')).toBe(false);+ expect(isOriginRepliableFrom(undefined, 'inkeep/open-knowledge')).toBe(false);+ });+});++describe('prerelease ordering', () => {+ test('a beta ranks below the stable that supersedes it', () => {+ expect(compareVersions('0.59.0-beta.9', '0.59.0')).toBeLessThan(0);+ expect(compareVersions('0.59.0', '0.59.0-beta.9')).toBeGreaterThan(0);+ });++ test('betas of one cycle order numerically, not as strings', () => {+ expect(compareVersions('0.59.0-beta.2', '0.59.0-beta.10')).toBeLessThan(0);+ });++ test('the highest across a fan-in spanning both channels is the stable', () => {+ // A three-part compare calls a beta equal to its stable, so whichever+ // arrived first would win and a reporter could be sent to a build that does+ // not carry every part of what they reported.+ expect(highestVersion(['0.59.0-beta.9', '0.59.0', '0.58.1'])).toBe('0.59.0');+ });+});++describe('the two channels say different things', () => {+ const changeset = {+ title: 'Configurable auto-sync cadence',+ body: 'Auto-sync cadence is now configurable.',+ };++ test('a stable reply claims the fix is out and points at the current app', () => {+ const text = composeReply({ changeset, version: '0.59.1', originChannel: 'github-issue' });+ expect(text).toContain('This shipped in Open Knowledge v0.59.1.');+ expect(text).toContain('update to the latest desktop app');+ expect(text).not.toMatch(/beta/i);+ });++ test('a beta reply names the beta, does not claim the default channel, and promises the follow-up', () => {+ const text = composeReply({+ changeset,+ version: '0.59.0-beta.2',+ originChannel: 'github-issue',+ channel: 'beta',+ });+ expect(text).toContain('v0.59.0-beta.2');+ expect(text).toContain('going out now on the Open Knowledge beta channel');+ expect(text).toContain('follow up here');+ // "update to the latest" would send them to a build without the fix: a beta+ // is not on the channel the desktop app follows.+ expect(text).not.toContain('update to the latest');+ expect(text).toContain('download the v0.59.0-beta.2 beta');+ // The release is still a draft when this posts, so nothing may claim the+ // build is already sitting on the releases page.+ expect(text).not.toMatch(/available now|download it now/i);+ expect(text).toContain('installers have finished uploading');+ });++ test('a Discord beta reply wraps the URL so it does not expand into an embed', () => {+ const text = composeReply({+ changeset,+ version: '0.59.0-beta.2',+ originChannel: 'discord-thread',+ channel: 'beta',+ });+ expect(text).toMatch(/<https:\/\/github\.com\/inkeep\/open-knowledge\/releases>/);+ });++ test('a channel that is neither refuses rather than composing a reply in the wrong voice', () => {+ expect(() =>+ composeReply({+ changeset,+ version: '0.59.1',+ originChannel: 'github-issue',+ channel: 'nightly',+ }),+ ).toThrow(/channel/);+ });++ test('a beta version is a version composeReply accepts', () => {+ expect(() =>+ composeReply({ changeset, version: 'nonsense', originChannel: 'github-issue' }),+ ).toThrow(/derived version/);+ });+});diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjsindex 6f2acb618..cf4884e52 100644--- a/.github/scripts/write-back.mjs+++ b/.github/scripts/write-back.mjs@@ -1,6 +1,10 @@#!/usr/bin/env node/**- * Tell a bug reporter, once, that the fix they reported has shipped.+ * Tell a reporter, at most once per channel, that the fix they reported is out.+ *+ * "A reporter", not "a bug reporter": the enumeration below does not narrow on the+ * Bug label, because whether someone hears back should not depend on how triage+ * classified what they raised.** Why this enumerates tickets rather than release commits. Every off-the-shelf* release notifier walks the commits in a release, follows each to its pull@@ -43,11 +47,19 @@ import {firstContainingStableTag,parseFixRef,parseGitOriginRevIds,+ realReleaseTags,resolvePrivateSha,resolveShippedVersion,+ sortReleaseTagsAscending,sortStableTagsAscending,} from './resolve-shipped-version.mjs';-import { composeReply, evaluateFanIn, partitionAttachments } from './write-back-gate.mjs';+import {+ compareVersions,+ composeReply,+ evaluateFanIn,+ isOriginRepliableFrom,+ partitionAttachments,+} from './write-back-gate.mjs';const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';const RELEASES_TAG_BASE = 'https://github.com/inkeep/open-knowledge/releases/tag';@@ -57,26 +69,37 @@ const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;const PAGE_SIZE = 50;/**- * The candidate enumeration.+ * The candidate enumeration: every completed ticket, and nothing narrower.+ *+ * It used to add `labels: { name: { eq: "Bug" } }`, and that label was the only+ * thing standing between a reporter and a reply. It is the wrong gate. A+ * community feature request that someone waited months for is exactly as+ * report-shaped as a bug, and triage that files it as `Feature` — or with only+ * a component label — made it permanently invisible here. Relabelling such a+ * ticket `Bug` is the other way out and is worse: the automated point-release+ * lane keys off that same label, so relabelling to fix a notification would+ * also change how the fix ships.*- * `labels: { name: { eq: "Bug" } }` matches when ANY of the ticket's labels is- * Bug, which is the intent: a real ticket looks like ["Bug", "ok:platform"].- * The sibling form `labels: { every: { name: { eq: "Bug" } } }` reads almost- * identically and would silently drop every multi-labelled ticket, which is to- * say nearly all of them. The colocated test pins that this query never uses- * `every`.+ * What replaces it is not another server-side predicate but the gates that were+ * always downstream, promoted to run first: a ticket needs an origin this+ * workflow can reply to, and a fix reference that resolves to a released build.+ * Those are the two facts a reply actually depends on, and a ticket missing+ * either was never going to be posted to whatever its labels said.*- * "Not yet notified" is deliberately absent from the filter. Linear's filter- * language has no negative-existence predicate over attachments, and expressing- * it as a positive one would invert the meaning; the check runs over the- * attachments this query already returns.+ * The cost of the wider net is enumeration volume, and it is paid in the+ * candidate loop rather than here: the origin check is pure and runs over the+ * attachments this query already returns, so the per-candidate children query+ * and the per-fix-reference `gh api` call are only reached by tickets that came+ * from outside. Linear's filter language has no attachment-existence predicate+ * that could have expressed it server-side, which is the same reason "not yet+ * notified" is absent from the filter and checked client-side.*/export const CANDIDATE_QUERY = `query WriteBackCandidates($after: String) {issues(first: ${PAGE_SIZE}after: $after- filter: { state: { type: { eq: "completed" } }, labels: { name: { eq: "Bug" } } }+ filter: { state: { type: { eq: "completed" } } }) {pageInfo { hasNextPage endCursor }nodes {@@ -184,6 +207,7 @@ export function deriveVersionForFixRefs({readCommitMessage = () => null,defaultRepo = DEFAULT_PRIVATE_REPO,selfRepo = process.env.GITHUB_REPOSITORY,+ channel = 'stable',log = () => {},}) {const usable = fixReferences.filter((ref) => ref.channel !== 'commit' || FULL_SHA_RE.test(ref.sha ?? ''));@@ -224,48 +248,99 @@ export function deriveVersionForFixRefs({// one that lacks their fix.const revIds = parseGitOriginRevIds(readCommitMessage(refSha) ?? '');if (revIds.length === 1) {- result = resolveShippedVersion({ privateSha: revIds[0], stableTags, findMirroredCommits, contains });+ result = resolveShippedVersion({+ privateSha: revIds[0],+ stableTags,+ findMirroredCommits,+ contains,+ channel,+ });} else {log(`::notice::write-back: ${ref.url} merges a commit with ${revIds.length === 0 ? 'no' : 'more than one'} ` +'origin trailer; falling back to direct tag containment of the merge commit itself.',);+ const sortedTags =+ channel === 'beta'+ ? sortReleaseTagsAscending(stableTags)+ : sortStableTagsAscending(stableTags);const tag = firstContainingStableTag({- sortedStableTags: sortStableTagsAscending(stableTags),+ sortedStableTags: sortedTags,sha: refSha,contains,});result = tag? { shipped: true, version: tag.replace(/^v/, ''), tag }- : { shipped: false, reason: 'not-in-any-stable' };+ : {+ shipped: false,+ reason: channel === 'beta' ? 'not-in-any-release' : 'not-in-any-stable',+ };}} else {- result = resolveShippedVersion({ privateSha: refSha, stableTags, findMirroredCommits, contains });+ result = resolveShippedVersion({+ privateSha: refSha,+ stableTags,+ findMirroredCommits,+ contains,+ channel,+ });}if (!result.shipped) {- log(`::notice::write-back: ${ref.url} has not reached a stable release yet (${result.reason}).`);+ log(+ `::notice::write-back: ${ref.url} has not reached a ${channel === 'beta' ? 'released build' : 'stable release'} ` ++ `yet (${result.reason}).`,+ );return null;}- if (highest === null || compareSemver(result.version, highest) > 0) highest = result.version;+ if (highest === null || compareVersions(result.version, highest) > 0) highest = result.version;}return highest;}-function compareSemver(a, b) {- const pa = a.split('.').map(Number);- const pb = b.split('.').map(Number);- for (let i = 0; i < 3; i += 1) {- if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);- }- return 0;-}export const DEFAULT_RELEASE_LOOKBACK = 3;-/** `v0.36.0` and `0.36.0` both mean the same release; anything else means none. */+/**+ * Betas are cut several times a day, so three of them can span less than a day+ * and a quiet weekend would age a reporter out of the window before anyone was+ * told. The stable lookback counts releases that land roughly weekly, which is+ * why the same number does not serve both. Nothing is lost by the wider beta+ * floor: the marker, not the window, is what stops a second reply.+ */+export const DEFAULT_BETA_LOOKBACK = 10;++/**+ * Which channel a release tag belongs to, or null when it is neither.+ *+ * A bare `vX.Y.Z` is the stable promotion; `vX.Y.Z-beta.N` is a beta cut. Any+ * other shape (a release candidate someone tags by hand, a moved pointer) is+ * refused rather than guessed at, because every downstream decision keys off+ * this answer and a wrong one addresses the reporter about the wrong build.+ */+export function deriveChannel(releaseTag) {+ const tag = String(releaseTag ?? '').trim();+ if (STABLE_TAG_RE.test(tag)) return 'stable';+ if (/^v\d+\.\d+\.\d+-beta\.\d+$/.test(tag)) return 'beta';+ return null;+}++/** True when a version string names a stable build rather than a beta. */+export function isStableVersion(raw) {+ return /^\d+\.\d+\.\d+$/.test(+ String(raw ?? '')+ .trim()+ .replace(/^v/, ''),+ );+}++/**+ * `v0.36.0` and `0.36.0` both mean the same release; anything else means none.+ * Beta versions are accepted too, so the beta channel's window can scope+ * against the prerelease tags it is actually cutting.+ */function normalizeVersion(raw) {const trimmed = String(raw ?? '').trim().replace(/^v/, '');- return /^\d+\.\d+\.\d+$/.test(trimmed) ? trimmed : null;+ return /^\d+\.\d+\.\d+(?:-beta\.\d+)?$/.test(trimmed) ? trimmed : null;}/**@@ -285,32 +360,39 @@ function normalizeVersion(raw) {* 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,-}) {+export function makeReleaseWindow({ releaseTag, stableTags = [], channel, 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)}). ` ++ `RELEASE_TAG must be a release tag of this cadence, v0.36.0 or v0.36.0-beta.3 ` ++ `(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);+ const resolvedChannel = channel ?? (isStableVersion(release) ? 'stable' : 'beta');+ const resolvedLookback =+ lookback ?? (resolvedChannel === 'beta' ? DEFAULT_BETA_LOOKBACK : DEFAULT_RELEASE_LOOKBACK);++ // `stableTags` is the raw `git tag --list v*` output, which carries the betas+ // too. The stable channel has to drop them here or its floor would be+ // computed over a list ten times denser than the stables it is counting, and+ // a lookback of three would reach back hours instead of weeks.+ const eligible = resolvedChannel === 'beta' ? () => true : (version) => isStableVersion(version);+ const known = [+ ...new Set(stableTags.map(normalizeVersion).filter(Boolean).filter(eligible)),+ ].sort(compareVersions);+ const atOrBelow = known.filter((v) => compareVersions(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 floorIndex = atOrBelow.length - (resolvedLookback + 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';+ if (compareVersions(shipped, release) > 0) return 'not-yet-shipped';+ if (floor && compareVersions(shipped, floor) <= 0) return 'shipped-earlier';return 'in-window';};}@@ -360,6 +442,8 @@ export async function runWriteBack({postReply,recordNotification,classifyRelease,+ channel = 'stable',+ selfRepo = process.env.GITHUB_REPOSITORY,live = false,log = () => {},}) {@@ -369,6 +453,23 @@ export async function runWriteBack({if (typeof classifyRelease !== 'function') {throw new Error('runWriteBack requires classifyRelease; see makeReleaseWindow.');}+ // Also no default. An unknown repo would make every GitHub origin look like+ // somebody else's, so the run would skip the entire candidate list as+ // `origin-elsewhere` and exit 0 looking like a quiet, healthy release. Refusing+ // is the only reading of a missing GITHUB_REPOSITORY that cannot be mistaken+ // for good news.+ // The two-value domain every downstream ternary decides over. Checking it here+ // rather than at the first `composeReply` means a misconfigured caller is+ // refused before the children query and the changeset reads, not after them.+ if (channel !== 'stable' && channel !== 'beta') {+ throw new Error(`runWriteBack requires channel 'stable' or 'beta', got '${channel}'`);+ }+ if (!String(selfRepo ?? '').trim()) {+ throw new Error(+ 'runWriteBack requires selfRepo (GITHUB_REPOSITORY): without it no GitHub origin can be ' ++ 'recognised as one this job may reply to, and every candidate would be skipped silently.',+ );+ }const posted = [];const skipped = [];@@ -381,12 +482,48 @@ export async function runWriteBack({// everyone reachable has been told, which is strictly more than aborting on// the first bad reference told anyone.const processCandidate = async (candidate) => {- const { origins, unrepliable, fixReferences } = partitionAttachments(candidate.attachmentUrls ?? []);+ const {+ origins: attachedOrigins,+ unrepliable,+ fixReferences,+ } = partitionAttachments(candidate.attachmentUrls ?? []);+ const origins = attachedOrigins.filter((origin) => isOriginRepliableFrom(origin, selfRepo));++ // Two cheap gates run before any network call, and their order is what makes+ // a label-free candidate list affordable. Everything below them costs a+ // GraphQL round trip for the children and a `gh api` call per fix reference;+ // everything at this point is a pure read of attachments the enumeration+ // already returned.+ //+ // First: is there anywhere to reply at all? A ticket with no origin, or one+ // whose only origins are issues in another product's repo, can never be+ // posted to from here no matter what else is true of it. A Slack archive is+ // the one shape that deliberately does NOT exit here: someone really is+ // waiting in that thread, so it stays on the full path and its warning can+ // still name the version they would have been told about, which is the whole+ // point of distinguishing it from silence. An uploaded file is not an origin+ // at all and exits here with everything else.+ if (origins.length === 0 && unrepliable.length === 0) {+ if (attachedOrigins.length > 0) {+ log(+ `::debug::write-back: ${candidate.identifier} reports from ` ++ `${attachedOrigins.map((o) => o.url).join(', ')}, outside ${selfRepo || 'this repo'}; ` ++ 'this job has no standing to post there.',+ );+ skip(candidate.identifier, 'origin-elsewhere');+ } else {+ // Not every fix has a reporter. This is the ordinary case, not a fault.+ skip(candidate.identifier, 'no-origin');+ }+ return;+ }+const children = await listChildren(candidate.id);// The version for every node in the tree is resolved up front so the gate// itself stays synchronous and pure.const considered = children.length > 0 ? children : [candidate];+const versions = new Map();for (const node of considered) {versions.set(node.identifier, await versionFor(node));@@ -401,12 +538,47 @@ export async function runWriteBack({if (gate.decision !== 'notify') {if (gate.unresolved.length > 0) {+ // "Nobody ever linked a pull request to this" and "a link exists and the+ // chain behind it is broken" both surface as an underivable version, and+ // they want opposite responses: the first is the ordinary state of a+ // ticket closed without a code change, the second is a fault worth+ // chasing. Now that the candidate list is no longer narrowed by label,+ // the first is much the commoner of the two, and folding it into a+ // warning would bury the fault under thousands of lines of routine.+ // Scoped to the unresolved nodes, not the whole tree. A fan-in where one+ // sibling resolved and another has no link at all would otherwise be+ // reported against the sibling that is fine, and the warning would tell+ // an operator to go check attachments that do not exist.+ const unresolvedWithRef = considered.filter(+ (node) =>+ gate.unresolved.includes(node.identifier) &&+ partitionAttachments(node.attachmentUrls ?? []).fixReferences.length > 0,+ );+ if (unresolvedWithRef.length === 0) {+ skip(candidate.identifier, 'no-fix-reference');+ return;+ }log(- `::warning::write-back: ${candidate.identifier} is done but no stable release could be derived for ` +- `${gate.unresolved.join(', ')}; posting nothing. Check the fix-reference attachments on those tickets.`,+ `::warning::write-back: ${candidate.identifier} is done but no ${channel === 'beta' ? 'released build' : 'stable release'} ` ++ `could be derived for ${unresolvedWithRef.map((n) => n.identifier).join(', ')}; posting nothing. ` ++ 'Check the fix-reference attachments on those tickets.',);+ skip(candidate.identifier, 'version-underivable');+ return;}- skip(candidate.identifier, gate.unresolved.length > 0 ? 'version-underivable' : 'fan-in-withheld');+ skip(candidate.identifier, 'fan-in-withheld');+ return;+ }++ // A beta run only has news when the earliest build carrying the fix is+ // itself a beta. When the first containing tag is a stable — a point release+ // that cherry-picked the fix straight onto the stable line, which happens+ // whenever the automated fix lane ships one — there is no beta to point at,+ // and the stable leg is the one that owns telling this reporter. Saying+ // "available now in beta v0.58.1" about a stable version would be wrong+ // twice: the channel and the promise of a follow-up.+ if (channel === 'beta' && isStableVersion(gate.version)) {+ skip(candidate.identifier, 'stable-covers-it');return;}@@ -419,17 +591,26 @@ export async function runWriteBack({return;}+ // Reaching here with no repliable origin means the ticket has only+ // unrepliable ones: the early gate above already returned on every other+ // shape. Kept on the full path precisely so this warning can name the+ // version, which is what makes it a report of a reachability gap rather than+ // one more line of silence.if (origins.length === 0) {- if (unrepliable.length > 0) {- log(- `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but its only origin ` +- `(${unrepliable.map((u) => u.channel).join(', ')}) has nowhere to post a reply; posting nothing.`,- );- skip(candidate.identifier, 'origin-unrepliable');- } else {- // Not every fix has a reporter. This is the ordinary case, not a fault.- skip(candidate.identifier, 'no-origin');- }+ // Names every origin that exists and cannot be answered, not just the+ // unrepliable ones. A ticket can carry a foreign-repo issue as well, and+ // calling the Slack link its "only" origin would hide that.+ const unreachable = [+ ...attachedOrigins+ .filter((origin) => !isOriginRepliableFrom(origin, selfRepo))+ .map((origin) => `${origin.channel} in ${origin.owner}/${origin.repo}`),+ ...unrepliable.map((u) => u.channel),+ ];+ log(+ `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but no origin on it can be ` ++ `replied to (${unreachable.join(', ')}); posting nothing.`,+ );+ skip(candidate.identifier, 'origin-unrepliable');return;}@@ -449,6 +630,7 @@ export async function runWriteBack({version: gate.version,originChannel: origin.channel,coverage: gate.coverage,+ channel,});if (!text) {@@ -465,7 +647,12 @@ export async function runWriteBack({`::notice::write-back: [dry run] would reply to ${origin.url} for ${candidate.identifier} ` +`(v${gate.version}, covers ${gate.coverage.join(', ')}).`,);- posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: true });+ posted.push({+ identifier: candidate.identifier,+ origin: origin.url,+ version: gate.version,+ dryRun: true,+ });continue;}@@ -498,8 +685,15 @@ export async function runWriteBack({'No future run will retry it; post the reply by hand.',);}- log(`::notice::write-back: replied to ${origin.url} for ${candidate.identifier} (v${gate.version}).`);- posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: false });+ log(+ `::notice::write-back: replied to ${origin.url} for ${candidate.identifier} (v${gate.version}).`,+ );+ posted.push({+ identifier: candidate.identifier,+ origin: origin.url,+ version: gate.version,+ dryRun: false,+ });}};@@ -623,7 +817,11 @@ export function isRetryableNetworkError(err) {for (let cur = err, depth = 0; cur && typeof cur === 'object' && depth < 5; cur = cur.cause, depth += 1) {if (cur.name === 'TimeoutError') return true;if (RETRYABLE_NETWORK_CODES.has(cur.code)) return true;- if (/fetch failed|socket hang up|other side closed|terminated|network/i.test(String(cur.message ?? ''))) {+ if (+ /fetch failed|socket hang up|other side closed|terminated|network/i.test(+ String(cur.message ?? ''),+ )+ ) {return true;}}@@ -776,7 +974,10 @@ async function paginate({ apiKey, query, variables, log }) {do {const data = await linearGraphql({ apiKey, query, variables: { ...variables, after }, log });const page = data?.issues;- if (!page) throw new Error('Linear returned no issues connection; refusing to treat that as an empty result.');+ if (!page)+ throw new Error(+ 'Linear returned no issues connection; refusing to treat that as an empty result.',+ );collected.push(...page.nodes.map(toNode));after = page.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;} while (after);@@ -786,18 +987,13 @@ async function paginate({ apiKey, query, variables, log }) {function runGit(args) {const res = spawnSync('git', args, { encoding: 'utf8' });if (res.status !== 0) {- throw new Error(`git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`);+ throw new Error(+ `git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,+ );}return String(res.stdout || '');}-function realStableTags() {- return runGit(['tag', '--list', 'v*', '--sort=version:refname'])- .split('\n')- .map((t) => t.trim())- .filter((t) => STABLE_TAG_RE.test(t));-}-function realReadCommitMessage(sha) {return runGit(['show', '-s', '--format=%B', sha]);}@@ -825,7 +1021,9 @@ function realFindMirroredCommits(privateSha) {}function realContains(tag, sha) {- const res = spawnSync('git', ['merge-base', '--is-ancestor', sha, `${tag}^{commit}`], { encoding: 'utf8' });+ const res = spawnSync('git', ['merge-base', '--is-ancestor', sha, `${tag}^{commit}`], {+ encoding: 'utf8',+ });if (res.status === 0) return true;if (res.status === 1) return false;throw new Error(@@ -939,11 +1137,19 @@ function realReadChangesetProse(_candidate, { fixReferences }) {let names;try {names = gh(- ['api', `repos/${pull.owner}/${pull.repo}/pulls/${pull.number}/files`, '--paginate', '--jq', '.[].filename'],+ [+ 'api',+ `repos/${pull.owner}/${pull.repo}/pulls/${pull.number}/files`,+ '--paginate',+ '--jq',+ '.[].filename',+ ],pull,);} catch (err) {- throw new Error(`gh api pulls/${pull.number}/files failed: ${String(err?.stderr || err?.message || '').trim()}`);+ throw new Error(+ `gh api pulls/${pull.number}/files failed: ${String(err?.stderr || err?.message || '').trim()}`,+ );}const changesetPath = findChangesetPath(names.split('\n'), { repo: pull.repo });@@ -963,7 +1169,9 @@ function realReadChangesetProse(_candidate, { fixReferences }) {pull,);} catch (err) {- throw new Error(`gh api contents/${changesetPath} failed: ${String(err?.stderr || err?.message || '').trim()}`);+ throw new Error(+ `gh api contents/${changesetPath} failed: ${String(err?.stderr || err?.message || '').trim()}`,+ );}const decoded = Buffer.from(raw.replace(/\s+/g, ''), 'base64').toString('utf8');@@ -983,7 +1191,12 @@ async function realPostReply(origin, text) {if (origin.channel === 'github-issue') {execFileSync('gh',- ['api', `repos/${origin.owner}/${origin.repo}/issues/${origin.number}/comments`, '-f', `body=${text}`],+ [+ 'api',+ `repos/${origin.owner}/${origin.repo}/issues/${origin.number}/comments`,+ '-f',+ `body=${text}`,+ ],{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },);return;@@ -1009,7 +1222,9 @@ async function realPostReply(origin, text) {signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),});if (!res.ok) {- throw new Error(`notify endpoint returned HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);+ throw new Error(+ `notify endpoint returned HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`,+ );}return;}@@ -1029,12 +1244,21 @@ async function main() {const live = process.env.WRITE_BACK_MODE === 'live';if (!live) {- log('::notice::write-back: running in dry-run mode (set WRITE_BACK_MODE=live to arm reporter replies).');+ 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 channel = deriveChannel(releaseTag);+ if (!channel) {+ throw new Error(+ `RELEASE_TAG must be a release tag of this cadence, v0.36.0 or v0.36.0-beta.3 ` ++ `(got ${JSON.stringify(releaseTag)}).`,+ );+ }- const stableTags = realStableTags();+ const stableTags = realReleaseTags();const versionFor = (node) =>deriveVersionForFixRefs({fixReferences: partitionAttachments(node.attachmentUrls ?? []).fixReferences,@@ -1043,13 +1267,15 @@ async function main() {contains: realContains,resolvePrMergeSha: realResolvePrMergeSha,readCommitMessage: realReadCommitMessage,+ channel,log,});- const classifyRelease = makeReleaseWindow({ releaseTag, stableTags });+ const classifyRelease = makeReleaseWindow({ releaseTag, stableTags, channel });+ const lookback = channel === 'beta' ? DEFAULT_BETA_LOOKBACK : DEFAULT_RELEASE_LOOKBACK;log(- `::notice::write-back: scoped to ${releaseTag} and the ${DEFAULT_RELEASE_LOOKBACK} stable releases before it; ` +- 'anything shipped earlier is left alone.',+ `::notice::write-back: ${channel} channel, scoped to ${releaseTag} and the ${lookback} ` ++ `${channel === 'beta' ? 'releases' : 'stable releases'} before it; anything shipped earlier is left alone.`,);if (!String(process.env.CROSS_REPO_TOKEN ?? '').trim()) {@@ -1064,6 +1290,7 @@ async function main() {listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId }, log }),versionFor,classifyRelease,+ channel,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.mjsindex 830ebb8eb..c8502055d 100644--- a/.github/scripts/write-back.test.mjs+++ b/.github/scripts/write-back.test.mjs@@ -3,13 +3,16 @@ import { describe, expect, test } from 'vitest';import {CANDIDATE_QUERY,changesetDirFor,+ DEFAULT_BETA_LOOKBACK,DEFAULT_RELEASE_LOOKBACK,+ deriveChannel,deriveVersionForFixRefs,findChangesetPath,isFixRepoInRemit,isRetryableNetworkError,isSelfRepoPr,isRetryableStatus,+ isStableVersion,LINEAR_RETRY_ATTEMPTS,LINEAR_RETRY_CAP_MS,linearGraphql,@@ -27,6 +30,7 @@ import {const GH_ISSUE = 'https://github.com/inkeep/open-knowledge/issues/769';const GH_PULL = 'https://github.com/inkeep/agents-private/pull/2844';const SLACK_ARCHIVE = 'https://inkeep.slack.com/archives/C016VCYCL74/p1727122965001469';+const LINEAR_UPLOAD = 'https://uploads.linear.app/abc/def/diagnostics.zip';const DISCORD_THREAD = 'https://discord.com/channels/1514363990740828223/1528881792063508610';const CHANGESET = { title: 'Honor backslash escapes', body: 'Honor backslash escapes in the markdown promoters.' };@@ -60,6 +64,7 @@ function harness(overrides = {}) {// 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 }),+ selfRepo: 'inkeep/open-knowledge',log: (m) => logs.push(m),...overrides,};@@ -73,11 +78,15 @@ describe('candidate enumeration', () => {expect(CANDIDATE_QUERY).not.toMatch(/commits?\s*\(/);});- test('the label filter matches any label, so a Bug ticket carrying a platform label is still enumerated', () => {- expect(CANDIDATE_QUERY).toContain('labels: { name: { eq: "Bug" } }');- // `labels: { every: ... }` reads almost the same and would drop every- // multi-labelled ticket, which in practice is nearly all of them.- expect(CANDIDATE_QUERY).not.toContain('every');+ test('no label narrows the enumeration, because a label was never what a reply depends on', () => {+ // The Bug label used to be the filter, and it silently excluded every+ // community feature request from ever being told its fix shipped. Whether a+ // reporter hears back must not depend on how triage classified them, so the+ // query narrows on nothing but completion and the real preconditions (an+ // origin, a fix reference) are checked against the data it returns.+ expect(CANDIDATE_QUERY).not.toMatch(/labels\s*:/);+ expect(CANDIDATE_QUERY).not.toContain('Bug');+ expect(CANDIDATE_QUERY).toContain('state: { type: { eq: "completed" } }');});test('the not-yet-notified condition is not expressed inside the query', () => {@@ -85,6 +94,20 @@ describe('candidate enumeration', () => {expect(CANDIDATE_QUERY).toContain('attachments');});+ test('the tag list comes from the shared boundary, never a private copy of it', () => {+ // A private `realStableTags` here filtered the list to bare vX.Y.Z, so no+ // prerelease ever reached the channel-aware resolver and the beta channel+ // resolved nothing in production. Every beta test injects its own tag list,+ // so the unit suite could not see it; this is what stands in for that.+ const source = readFileSync(new URL('./write-back.mjs', import.meta.url), 'utf8');+ expect(source).toMatch(/import \{[^}]*\brealReleaseTags\b[^}]*\} from '\.\/resolve-shipped-version\.mjs'/s);+ expect(source).not.toMatch(/^function real(?:Stable|Release)Tags/m);+ // The list reaches the resolver exactly as git gave it. Narrowing it here,+ // at the definition or at the call site, is the whole failure.+ expect(source).toMatch(/const stableTags = realReleaseTags\(\);/);+ expect(source).not.toMatch(/Tags[^\n]*\.filter\([^\n]*STABLE_TAG_RE/);+ });+test('the module imports the shared shipped-version resolver rather than reimplementing containment', () => {const source = readFileSync(new URL('./write-back.mjs', import.meta.url), 'utf8');expect(source).toMatch(/from '\.\/resolve-shipped-version\.mjs'/);@@ -160,6 +183,47 @@ describe('version derivation', () => {expect(derive({ fixReferences: [] })).toBeNull();});+ test('the beta channel threads through to the resolver and answers with the beta', () => {+ // The seam this whole feature hangs off: deriveVersionForFixRefs ->+ // resolveShippedVersion with a channel. Same fix, same inputs, two answers.+ const shared = {+ fixReferences: [{ channel: 'pull-request', url: GH_PULL }],+ stableTags: [...STABLE_TAGS, 'v0.37.0-beta.0', 'v0.37.0-beta.1'],+ contains: containsFrom({ [MIRRORED_SHA]: ['v0.37.0-beta.0', 'v0.37.0-beta.1'] }),+ };+ expect(derive({ ...shared, channel: 'beta' })).toBe('0.37.0-beta.0');+ // No stable carries it yet, so the stable channel correctly has no answer.+ expect(derive(shared)).toBeNull();+ });++ test('the beta channel still yields nothing for a fix that is in no tag at all', () => {+ expect(+ derive({+ fixReferences: [{ channel: 'pull-request', url: GH_PULL }],+ contains: () => false,+ channel: 'beta',+ }),+ ).toBeNull();+ });++ test('the mirror-PR containment fallback honours the channel it was given', () => {+ // A mirror merge commit with no usable origin trailer falls back to direct+ // containment, which is a second place the tag list has to be channel-aware.+ const mirrorMain = 'd'.repeat(40);+ expect(+ deriveVersionForFixRefs({+ fixReferences: [{ channel: 'pull-request', url: 'https://github.com/inkeep/open-knowledge/pull/928' }],+ stableTags: [...STABLE_TAGS, 'v0.37.0-beta.0'],+ selfRepo: 'inkeep/open-knowledge',+ resolvePrMergeSha: () => mirrorMain,+ readCommitMessage: () => 'subject carrying no trailer at all',+ findMirroredCommits: () => [],+ contains: (tag, sha) => sha === mirrorMain && tag === 'v0.37.0-beta.0',+ channel: 'beta',+ }),+ ).toBe('0.37.0-beta.0');+ });+test('a mirror pull request in this repo resolves through its merge commit trailer', () => {// The Copybara mirror lands every export through a short-lived PR in this// repo, and Linear's linkback attaches it to the ticket. Its merge commit@@ -496,7 +560,7 @@ describe('write-back run', () => {const result = await h.run();expect(h.writes).toEqual([]);expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-unrepliable' }]);- expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('nowhere to post'))).toBe(true);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no origin on it can be replied to'))).toBe(true);});test('a candidate with no origin at all is skipped quietly, because not every fix has a reporter', async () => {@@ -1011,9 +1075,25 @@ describe('workflow shape', () => {expect(workflow).not.toContain('types: [published]');});- test('only a bare stable tag runs the write-back', () => {+ test('both release channels run, and a tag of neither shape runs nothing', () => {expect(workflow).toContain('^v[0-9]+\\.[0-9]+\\.[0-9]+$');- expect(workflow).toMatch(/if:\s*steps\.tag\.outputs\.stable == 'true'/);+ expect(workflow).toContain('^v[0-9]+\\.[0-9]+\\.[0-9]+-beta\\.[0-9]+$');+ expect(workflow).toContain("echo \"channel=stable\"");+ expect(workflow).toContain("echo \"channel=beta\"");+ expect(workflow).toContain("echo \"channel=none\"");+ // Every step that does real work stays behind the gate, so a tag of neither+ // shape reaches nothing: no checkout, no token mint, no reply.+ expect(workflow).toMatch(/if:\s*steps\.tag\.outputs\.channel != 'none'/);+ expect(workflow).not.toMatch(/steps\.tag\.outputs\.stable/);+ });++ test('no working step is left outside the channel gate', () => {+ // A step that forgot the gate would run on a tag the script then refuses,+ // which reads as a red write-back on an ordinary release.+ const stepNames = [...workflow.matchAll(/^ {6}- (?:name:.*|uses:.*)$/gm)].length;+ const gated = [...workflow.matchAll(/if: steps\.tag\.outputs\.channel != 'none'/g)].length;+ // Every step but the channel decision itself is gated.+ expect(gated).toBe(stepNames - 1);});test('it carries its own concurrency group so a release can never queue behind it', () => {@@ -1126,11 +1206,36 @@ describe('release window', () => {});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']) {+ for (const bad of [undefined, '', ' ', 'latest', 'v0.36.0-rc.1', 'v0.36']) {expect(() => makeReleaseWindow({ releaseTag: bad, stableTags: TAGS })).toThrow(/RELEASE_TAG/);}});+ test('a beta tag is a release this runs for, not a malformed one', () => {+ const window = makeReleaseWindow({+ releaseTag: 'v0.36.0-beta.1',+ stableTags: [...TAGS, 'v0.36.0-beta.0', 'v0.36.0-beta.1'],+ });+ expect(window('0.36.0-beta.0')).toBe('in-window');+ expect(window('0.36.0-beta.1')).toBe('in-window');+ // The stable of the same cycle supersedes the beta, so it has not shipped+ // yet from the beta run's point of view.+ expect(window('0.36.0')).toBe('not-yet-shipped');+ });++ test('a stable run counts stables, so the betas between them cannot eat the lookback', () => {+ // `git tag --list v*` hands over the betas too. If the stable window counted+ // them, three releases back would reach hours rather than weeks and the+ // catch-up the lookback exists for would stop happening.+ const dense = ['v0.33.0', 'v0.34.0', 'v0.35.0', 'v0.36.0'].flatMap((tag) => [+ `${tag}-beta.0`,+ `${tag}-beta.1`,+ tag,+ ]);+ const window = makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: dense });+ expect(window('0.33.0')).toBe('in-window');+ });+test('the default lookback is three', () => {expect(DEFAULT_RELEASE_LOOKBACK).toBe(3);});@@ -1178,3 +1283,318 @@ describe('release window applied to a run', () => {await expect(h.run()).rejects.toThrow(/classifyRelease/);});});++describe('release channels', () => {+ test('the two tag shapes this repo cuts are the two channels, and nothing else is a release', () => {+ expect(deriveChannel('v0.36.0')).toBe('stable');+ expect(deriveChannel('v0.36.0-beta.3')).toBe('beta');+ for (const bad of [+ undefined,+ '',+ 'v0.36.0-rc.1',+ '0.36.0',+ 'v0.36',+ 'latest',+ 'v0.36.0-beta',+ ]) {+ expect(deriveChannel(bad)).toBeNull();+ }+ });++ test('a beta version is not a stable one, which is what keeps the two replies apart', () => {+ expect(isStableVersion('0.36.0')).toBe(true);+ expect(isStableVersion('v0.36.0')).toBe(true);+ expect(isStableVersion('0.36.0-beta.0')).toBe(false);+ });++ test('the beta lookback is wider than the stable one, because betas cut far more often', () => {+ // Three betas can span less than a day, so reusing the stable number would+ // age a reporter out of the window over a quiet weekend.+ expect(DEFAULT_BETA_LOOKBACK).toBeGreaterThan(DEFAULT_RELEASE_LOOKBACK);+ });+});++describe('origin remit', () => {+ const foreignIssue = 'https://github.com/inkeep/agents/issues/412';++ test('a report from another repo is passed over instead of attempted', async () => {+ // The reply is posted with this job's own token, which has no standing in+ // any other repository. Attempting it would 403 and turn a run that behaved+ // correctly red, on a ticket it was never meant to speak about.+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, foreignIssue] })],+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-elsewhere' }]);+ expect(result.errored).toEqual([]);+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);+ });++ test('a foreign origin costs no round trip, which is what makes the wider candidate list affordable', async () => {+ // The gate has to sit in front of the children query, not behind it. With+ // no label narrowing the enumeration, every completed ticket in the+ // workspace arrives here; one GraphQL call each would exhaust the API+ // budget long before the run finished.+ let childrenCalls = 0;+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, foreignIssue] })],+ listChildren: async () => {+ childrenCalls += 1;+ return [];+ },+ versionFor: async () => {+ throw new Error('a foreign-origin candidate must never reach version resolution');+ },+ });+ await h.run();+ expect(childrenCalls).toBe(0);+ });++ test('a ticket whose only extra attachment is an upload is passed over as having no origin', async () => {+ // `uploads.linear.app` is a screenshot or a diagnostic zip, which is most of+ // the workspace once no label narrows the enumeration. Reading it as an+ // origin both kept those tickets on the expensive path and warned that their+ // "only origin" had nowhere to post a reply, which was never true.+ let childrenCalls = 0;+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, LINEAR_UPLOAD] })],+ listChildren: async () => {+ childrenCalls += 1;+ return [];+ },+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-origin' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);+ expect(childrenCalls).toBe(0);+ });++ test('the reachability warning names every origin that cannot be answered, not just one', async () => {+ // A ticket can carry both a foreign-repo issue and a Slack link. Calling the+ // Slack link its "only" origin would hide the other one from an operator.+ const h = harness({+ live: true,+ listCandidates: async () => [+ candidate({ attachmentUrls: [GH_PULL, 'https://github.com/inkeep/agents/issues/412', SLACK_ARCHIVE] }),+ ],+ });+ const result = await h.run();+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-unrepliable' }]);+ const warning = h.logs.find((m) => m.startsWith('::warning::'));+ expect(warning).toContain('inkeep/agents');+ expect(warning).toContain('slack-archive');+ expect(warning).not.toContain('only origin');+ });++ test('a Slack archive is still a real origin, so it still reports a reachability gap', async () => {+ // Someone IS waiting in that thread; this workflow simply cannot post there.+ // That distinction is the whole reason `unrepliable` stays on the full path.+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, SLACK_ARCHIVE] })],+ });+ const result = await h.run();+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-unrepliable' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no origin on it can be replied to'))).toBe(true);+ });++ test('a Discord thread is repliable wherever it lives, because the bot is not repo-scoped', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, DISCORD_THREAD] })],+ });+ await h.run();+ expect(h.writes.filter((w) => w.kind === 'post')).toHaveLength(1);+ });++ test('an unknown self repo refuses the run rather than skipping every candidate as foreign', async () => {+ // The dangerous reading of a missing GITHUB_REPOSITORY is the quiet one: no+ // origin matches, every candidate is skipped, and the run exits 0 looking+ // like a healthy release in which nobody happened to need telling.+ //+ // The env var is stubbed rather than left alone: `selfRepo: undefined` falls+ // through to the destructuring default, so under Actions the runner's own+ // GITHUB_REPOSITORY would satisfy a check this test exists to see fail.+ const previous = process.env.GITHUB_REPOSITORY;+ delete process.env.GITHUB_REPOSITORY;+ try {+ for (const missing of [undefined, '', ' ']) {+ const h = harness({ live: true, selfRepo: missing });+ await expect(h.run()).rejects.toThrow(/selfRepo|GITHUB_REPOSITORY/);+ }+ } finally {+ if (previous === undefined) delete process.env.GITHUB_REPOSITORY;+ else process.env.GITHUB_REPOSITORY = previous;+ }+ });++ test('a channel that is neither is refused at the entry point, before any round trip', async () => {+ // Every downstream decision is a `channel === 'beta'` ternary, so an+ // unexpected value would quietly behave as stable all the way to the reply.+ const h = harness({+ live: true,+ channel: 'nightly',+ listChildren: async () => {+ throw new Error('an invalid channel must be refused before the children query');+ },+ });+ await expect(h.run()).rejects.toThrow(/channel/);+ });+});++describe('a linked pull request, not a label, is what a reply depends on', () => {+ test('a ticket nobody linked a fix to is passed over quietly, not warned about', async () => {+ // This is the ordinary state of a completed ticket that carried no code+ // change, and with the label filter gone it is much the commonest outcome of+ // a run. Warning on it would bury the genuine broken-chain warning under it.+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_ISSUE] })],+ versionFor: async () => null,+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-fix-reference' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);+ });++ test('a fix reference that exists and does not resolve still warns, because that is a broken chain', async () => {+ const h = harness({ live: true, versionFor: async () => null });+ const result = await h.run();+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'version-underivable' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('could be derived'))).toBe(+ true,+ );+ });++ test('a sibling that resolved does not make an unlinked sibling look like a broken chain', async () => {+ // One child shipped, the other was closed with no pull request at all. The+ // warning must not name the child that is fine, and must not send an+ // operator looking for attachments the other one never had.+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_ISSUE] })],+ listChildren: async () => [+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: [], attachmentUrls: [GH_PULL] },+ { id: 'b', identifier: 'PRD-7401', stateType: 'completed', labels: [], attachmentUrls: [] },+ ],+ versionFor: async (node) => (node.identifier === 'PRD-7398' ? '0.36.0' : null),+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-fix-reference' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);+ });++ test('the broken-chain warning names only the tickets that actually carry a link', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_ISSUE] })],+ listChildren: async () => [+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: [], attachmentUrls: [GH_PULL] },+ { id: 'b', identifier: 'PRD-7401', stateType: 'completed', labels: [], attachmentUrls: [] },+ ],+ versionFor: async () => null,+ });+ const result = await h.run();+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'version-underivable' }]);+ const warning = h.logs.find((m) => m.startsWith('::warning::') && m.includes('could be derived'));+ expect(warning).toContain('PRD-7398');+ expect(warning).not.toContain('PRD-7401');+ });++ test('a fix reference on a child counts for the parent that has none of its own', async () => {+ // A report that fanned out carries its links on the children. Looking only+ // at the parent would file every fanned-in report as unlinked.+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_ISSUE] })],+ listChildren: async () => [+ {+ id: 'a',+ identifier: 'PRD-7398',+ stateType: 'completed',+ labels: [],+ attachmentUrls: [GH_PULL],+ },+ ],+ versionFor: async () => null,+ });+ const result = await h.run();+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'version-underivable' }]);+ });+});++describe('the beta leg', () => {+ const BETA_TAGS = [...STABLE_TAGS, 'v0.37.0-beta.0', 'v0.37.0-beta.1'];+ const betaHarness = (overrides = {}) =>+ harness({+ live: true,+ channel: 'beta',+ versionFor: async () => '0.37.0-beta.0',+ classifyRelease: makeReleaseWindow({ releaseTag: 'v0.37.0-beta.1', stableTags: BETA_TAGS }),+ ...overrides,+ });++ test('a fix whose earliest build is a beta is announced as a beta, with the stable promised', async () => {+ const h = betaHarness();+ await h.run();+ const post = h.writes.find((w) => w.kind === 'post');+ expect(post.text).toContain('v0.37.0-beta.0');+ expect(post.text).toContain('going out now on the Open Knowledge beta channel');+ expect(post.text).toContain('follow up here');+ expect(post.text).not.toContain('This shipped in');+ });++ test('the beta marker is not the stable one, so each channel is told at most once', async () => {+ const beta = betaHarness();+ await beta.run();+ const stable = harness({ live: true });+ await stable.run();+ const betaMark = beta.writes.find((w) => w.kind === 'mark').url;+ const stableMark = stable.writes.find((w) => w.kind === 'mark').url;+ expect(betaMark).not.toBe(stableMark);+ expect(betaMark).toContain('v0.37.0-beta.0');+ });++ test('a later beta of the same cycle re-reads the same marker and says nothing more', async () => {+ // The beta version is the FIRST tag containing the fix, so it does not move+ // as the cycle cuts beta.1, beta.2 and so on. That is what stops a reporter+ // being pinged once per beta.+ const marked = notificationMarkerUrl({ version: '0.37.0-beta.0', originUrl: GH_ISSUE });+ const h = betaHarness({+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, GH_ISSUE, marked] })],+ classifyRelease: makeReleaseWindow({+ releaseTag: 'v0.37.0-beta.5',+ stableTags: [...BETA_TAGS, 'v0.37.0-beta.5'],+ }),+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'already-notified' }]);+ });++ test('a fix that only ever appeared in a stable is left to the stable leg', async () => {+ // A point release cherry-picks a fix straight onto the stable line, so its+ // earliest containing tag is a stable and there is no beta to point anyone+ // at. Announcing it here would name a stable version as a beta and promise a+ // follow-up that the stable leg has already made.+ const h = betaHarness({ versionFor: async () => '0.35.6' });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'stable-covers-it' }]);+ });++ test('the stable leg still speaks in stable terms once the promotion happens', async () => {+ const h = harness({ live: true });+ await h.run();+ const post = h.writes.find((w) => w.kind === 'post');+ expect(post.text).toContain('This shipped in Open Knowledge v0.36.0');+ expect(post.text).not.toContain('beta');+ });+});diff --git a/.github/workflows/write-back.yml b/.github/workflows/write-back.ymlindex ffb54ee18..f693a17d1 100644--- a/.github/workflows/write-back.yml+++ b/.github/workflows/write-back.yml@@ -1,6 +1,10 @@name: Reporter Write-Back-# Tell bug reporters, once, that the fix they reported has shipped.+# Tell a reporter, at most once per channel, that the fix they reported is out.+#+# "A reporter", not "a bug reporter": the candidate enumeration no longer+# narrows on the Bug label, because whether someone hears back should not depend+# on how triage classified what they raised.## HOW IT'S TRIGGERED (no edits to the delicate publish path)# release.yml (beta) and promote-stable.yml (stable) both already fire a@@ -11,9 +15,18 @@ name: Reporter Write-Back# cascades from GITHUB_TOKEN-authored release events, and repository_dispatch# is the documented exemption.#-# Only a bare vX.Y.Z runs. A `-beta.N` cut is a no-op: a reporter told their-# fix is out should be able to install it from the default channel, and a beta-# is not that.+# BOTH channels run, and they say different things. A `-beta.N` cut tells the+# reporter their fix is available now in a beta and that a second message is+# coming; the stable promotion sends that second message. The two are kept+# apart by their notification markers, which key on the version, so neither can+# fire twice and a cycle that cuts beta.0 through beta.7 still produces exactly+# one beta reply.+#+# This used to be stable-only, on the reasoning that a reporter told "your fix+# is out" should be able to install it from the default channel. That reasoning+# holds, and it is why the beta reply does not make that claim: it names the+# beta as a beta, points at a build that must be downloaded deliberately, and+# promises the follow-up rather than implying none is coming.## WHY IT IS DECOUPLED# This posts in public under the project's name and it runs after a release@@ -43,7 +56,7 @@ on:workflow_dispatch:inputs:release_tag:- description: "Stable release tag to notify reporters about (e.g. v0.36.0)"+ description: "Release tag to notify reporters about (e.g. v0.36.0 or v0.36.0-beta.3)"required: truetype: string@@ -65,7 +78,7 @@ jobs:env:RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}steps:- - name: Decide whether this tag is a stable release+ - name: Decide which release channel this tag belongs toid: tagrun: |set -euo pipefail@@ -74,24 +87,27 @@ jobs:exit 1fiif [[ "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then- echo "stable=true" >> "$GITHUB_OUTPUT"+ echo "channel=stable" >> "$GITHUB_OUTPUT"+ elif [[ "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$ ]]; then+ echo "channel=beta" >> "$GITHUB_OUTPUT"else- echo "stable=false" >> "$GITHUB_OUTPUT"- echo "::notice::${RELEASE_TAG} is not a bare stable tag; reporters are only told about stable releases."+ echo "channel=none" >> "$GITHUB_OUTPUT"+ echo "::notice::${RELEASE_TAG} is neither a stable nor a beta tag of this cadence; there is no build to tell anyone about."fi- name: Checkout with full history and tags- if: steps.tag.outputs.stable == 'true'+ if: steps.tag.outputs.channel != 'none'uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1with:# Tag containment is how the shipped version is derived, so every- # stable tag and the full history behind them have to be present.+ # release tag of both channels and the full history behind them have+ # to be present.fetch-depth: 0fetch-tags: truepersist-credentials: false- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0- if: steps.tag.outputs.stable == 'true'+ if: steps.tag.outputs.channel != 'none'with:node-version: "24"@@ -99,7 +115,7 @@ jobs:# Fix references point into the private monorepo, which this repo's own# token cannot read at all. Secrets are unreadable in `if:` expressions,# so the presence check runs here and gates the mint via an output.- if: steps.tag.outputs.stable == 'true'+ if: steps.tag.outputs.channel != 'none'id: bridge-checkenv:OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}@@ -113,7 +129,7 @@ jobs:fi- name: Mint cross-repo read token (bridge App)- if: steps.tag.outputs.stable == 'true' && steps.bridge-check.outputs.configured == 'true'+ if: steps.tag.outputs.channel != 'none' && steps.bridge-check.outputs.configured == 'true'id: bridge-tokenuses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1with:@@ -129,7 +145,7 @@ jobs:permission-pull-requests: read- name: Notify reporters whose fix reached this release- if: steps.tag.outputs.stable == 'true'+ if: steps.tag.outputs.channel != 'none'env:# Posting the reply, which happens against this repo.GH_TOKEN: ${{ github.token }}