Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.mjs
index 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, findMirroredComm
return { 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.mjs
index 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.mjs
index 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, coverage
const 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.mjs
index 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.mjs
index 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.mjs
index 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.yml
index 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: true
type: 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 to
id: tag
run: |
set -euo pipefail
@@ -74,24 +87,27 @@ jobs:
exit 1
fi
if [[ "${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.1
with:
# 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: 0
fetch-tags: true
persist-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-check
env:
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-token
uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
with:
@@ -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 }}