feat(actions): generate Linear webgui release notes

- Purpose: let the webgui tag workflow own user-facing Linear release notes for the active tag.\n- Before: the workflow synced Linear releases and issue membership but did not write release notes from the tag's commit or PR range.\n- Problem: stable release notes were being filled by release-diff internals instead of webgui-facing release context.\n- New behavior: the workflow records PR summaries, linked Linear IDs, FeatureOS links, and commit metadata, then syncs an idempotent Version <tag> release note.\n- How it works: the collection step emits PR summary and log paths, and the Node sync script creates or updates a marker-managed Linear release note attached to the active tag release.

Author: elibosley

.github/scripts/sync-linear-release.mjs

@@ -24,6 +24,8 @@ const tagSha = requiredEnv("TAG_SHA");
 const issueIdsPath = requiredEnv("ISSUE_IDS_PATH");
 const featureOsUrlsPath = env.FEATUREOS_URLS_PATH;
 const githubPrUrlsPath = env.GITHUB_PR_URLS_PATH;
+const prSummaryPath = env.PR_SUMMARY_PATH;
+const logPath = env.LOG_PATH;
 
 const pipelineName = RELEASE_PIPELINE_BY_CHANNEL[releaseChannel];
 if (!pipelineName) {
@@ -38,6 +40,7 @@ const githubPrUrls = githubPrUrlsPath ? readLines(githubPrUrlsPath) : [];
 const pipeline = await findReleasePipeline(pipelineName);
 const targetStage = findStage(pipeline, targetStageName);
 const release = await upsertRelease({ pipeline, targetStage });
+await syncWebguiReleaseNotes(pipeline, release);
 const relatedReleases = await resolveRelatedReleases(pipeline);
 const syncResult = await syncIssuesToRelease(release, relatedReleases, { issueIdentifiers, featureOsUrls, githubPrUrls });
 
@@ -304,6 +307,13 @@ async function findRelease(pipelineId, version, name) {
             name
             type
           }
+          releaseNotes {
+            id
+            title
+            documentContent {
+              content
+            }
+          }
         }
       }
     }
@@ -331,6 +341,13 @@ async function createRelease(input) {
             name
             type
           }
+          releaseNotes {
+            id
+            title
+            documentContent {
+              content
+            }
+          }
         }
       }
     }
@@ -360,6 +377,13 @@ async function updateRelease(id, input) {
             name
             type
           }
+          releaseNotes {
+            id
+            title
+            documentContent {
+              content
+            }
+          }
         }
       }
     }
@@ -372,6 +396,124 @@ async function updateRelease(id, input) {
   return data.releaseUpdate.release;
 }
 
+async function syncWebguiReleaseNotes(pipeline, release) {
+  const content = buildWebguiReleaseNotes();
+  if (!content || !release?.id) {
+    return;
+  }
+
+  const title = `Version ${tagName}`;
+  const existingNote = findReleaseNote(release, title);
+  const nextContent = renderManagedSection(
+    existingNote?.documentContent?.content || "",
+    "notification-worker-webgui-release-notes",
+    title,
+    content,
+  );
+
+  if (existingNote?.id) {
+    if (nextContent !== (existingNote.documentContent?.content || "") || existingNote.title !== title) {
+      await updateReleaseNote(existingNote.id, {
+        releaseId: release.id,
+        title,
+        content: nextContent,
+      });
+    }
+    return;
+  }
+
+  await createReleaseNote({
+    pipelineId: pipeline.id,
+    releaseId: release.id,
+    title,
+    content: nextContent,
+  });
+}
+
+function buildWebguiReleaseNotes() {
+  const prSummaries = prSummaryPath ? readOptionalLines(prSummaryPath) : [];
+  const commitSubjects = logPath ? readCommitSubjects(logPath) : [];
+  const metadata = [
+    `Tag: \`${tagName}\``,
+    `Commit: \`${tagSha}\``,
+    env.PREVIOUS_TAG ? `Previous tag: \`${env.PREVIOUS_TAG}\`` : undefined,
+    env.RANGE_SPEC ? `Commit range: \`${env.RANGE_SPEC}\`` : undefined,
+  ].filter(Boolean);
+  const sections = [["## Release Metadata", ...metadata]];
+
+  if (prSummaries.length > 0) {
+    sections.push(["## WebGUI Pull Requests", ...prSummaries]);
+  }
+  if (issueIdentifiers.length > 0) {
+    sections.push(["## Linked Linear Issues", ...issueIdentifiers.map((id) => `- ${id}`)]);
+  }
+  if (featureOsUrls.length > 0) {
+    sections.push(["## Linked FeatureOS Posts", ...featureOsUrls.map((url) => `- ${url}`)]);
+  }
+  if (prSummaries.length === 0 && commitSubjects.length > 0) {
+    sections.push(["## Commit Summary", ...commitSubjects.slice(0, 25).map((subject) => `- ${subject}`)]);
+  }
+
+  return sections.map((section) => section.join("\n")).join("\n\n").trim();
+}
+
+function findReleaseNote(release, title) {
+  const normalizedTitle = title.trim().toLowerCase();
+  const marker = managedSectionStartMarker("notification-worker-webgui-release-notes", title);
+  return (release.releaseNotes || []).find((note) => (note.title || "").trim().toLowerCase() === normalizedTitle)
+    || (release.releaseNotes || []).find((note) => (note.documentContent?.content || "").includes(marker));
+}
+
+async function createReleaseNote(input) {
+  const data = await graphql(`
+    mutation CreateReleaseNote($input: ReleaseNoteCreateInput!) {
+      releaseNoteCreate(input: $input) {
+        success
+        releaseNote {
+          id
+          title
+        }
+      }
+    }
+  `, {
+    input: dropUndefined({
+      pipelineId: input.pipelineId,
+      releaseIds: [input.releaseId],
+      title: input.title,
+      content: input.content,
+    }),
+  });
+
+  if (!data.releaseNoteCreate.success) {
+    throw new Error(`Linear release note create failed for ${input.releaseId}`);
+  }
+}
+
+async function updateReleaseNote(id, input) {
+  const data = await graphql(`
+    mutation UpdateReleaseNote($id: String!, $input: ReleaseNoteUpdateInput!) {
+      releaseNoteUpdate(id: $id, input: $input) {
+        success
+        releaseNote {
+          id
+          title
+        }
+      }
+    }
+  `, {
+    id,
+    input: dropUndefined({
+      releaseIds: [input.releaseId],
+      title: input.title,
+      content: input.content,
+    }),
+  });
+
+  if (!data.releaseNoteUpdate.success) {
+    throw new Error(`Linear release note update failed for ${id}`);
+  }
+}
+
 async function findIssue(identifier) {
   const data = await graphql(`
     query FindIssue($id: String!) {
@@ -548,6 +690,67 @@ function readLines(path) {
     .filter((value, index, values) => values.indexOf(value) === index);
 }
 
+function readOptionalLines(path) {
+  try {
+    return readLines(path);
+  } catch {
+    return [];
+  }
+}
+
+function readCommitSubjects(path) {
+  try {
+    return readFileSync(path, "utf8")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("Merge pull request #"))
+      .filter((value, index, values) => values.indexOf(value) === index);
+  } catch {
+    return [];
+  }
+}
+
+function renderManagedSection(content, markerPrefix, title, body) {
+  const normalizedTitle = title.trim() || "Release Notes";
+  const normalizedBody = body.trim();
+  if (!normalizedBody) {
+    return content;
+  }
+
+  const startMarker = managedSectionStartMarker(markerPrefix, normalizedTitle);
+  const endMarker = `<!-- ${markerPrefix}:end:${stableMarkerHash(normalizedTitle)} -->`;
+  const section = [
+    startMarker,
+    `# ${normalizedTitle}`,
+    "",
+    normalizedBody,
+    endMarker,
+  ].join("\n").trim();
+  const existing = content.trim();
+  const pattern = new RegExp(`${escapeRegExp(startMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}`, "m");
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, section).trim();
+  }
+
+  return [existing, section].filter(Boolean).join("\n\n").trim();
+}
+
+function managedSectionStartMarker(markerPrefix, title) {
+  return `<!-- ${markerPrefix}:start:${stableMarkerHash(title.trim() || "Release Notes")} -->`;
+}
+
+function stableMarkerHash(value) {
+  let hash = 5381;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) + hash) ^ value.charCodeAt(index);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function candidateAttachmentUrls(url) {
   const candidates = new Set([url]);
   try {

.github/workflows/linear-release.yml

@@ -113,11 +113,13 @@ jobs:
           ISSUE_IDS_PATH="${RUNNER_TEMP}/linear-release-issue-ids.txt"
           FEATUREOS_URLS_PATH="${RUNNER_TEMP}/linear-release-featureos-urls.txt"
           GITHUB_PR_URLS_PATH="${RUNNER_TEMP}/linear-release-github-pr-urls.txt"
+          PR_SUMMARY_PATH="${RUNNER_TEMP}/linear-release-pr-summary.txt"
           : > "$LOG_PATH"
           : > "$PR_TEXT_PATH"
           : > "$ISSUE_IDS_PATH"
           : > "$FEATUREOS_URLS_PATH"
           : > "$GITHUB_PR_URLS_PATH"
+          : > "$PR_SUMMARY_PATH"
 
           git log --format='%B%n' "$RANGE_SPEC" > "$LOG_PATH"
 
@@ -128,14 +130,24 @@ jobs:
           )"
 
           for PR_NUMBER in $PR_NUMBERS; do
-            echo "${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" >> "$GITHUB_PR_URLS_PATH"
+            PR_URL="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
+            PR_JSON_PATH="$(mktemp)"
+            echo "${PR_URL}" >> "$GITHUB_PR_URLS_PATH"
             curl -fsSL \
               -H "Accept: application/vnd.github+json" \
               -H "Authorization: Bearer ${GH_TOKEN}" \
               -H "X-GitHub-Api-Version: 2022-11-28" \
               "${GITHUB_API_URL:-https://api.github.com}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
-              | jq -r '[.title, .body, .head.ref, .base.ref] | map(select(. != null and . != "")) | .[]' \
-              >> "$PR_TEXT_PATH"
+              > "$PR_JSON_PATH"
+            jq -r '[.title, .body, .head.ref, .base.ref] | map(select(. != null and . != "")) | .[]' \
+              "$PR_JSON_PATH" >> "$PR_TEXT_PATH"
+            PR_TITLE="$(jq -r '.title // ""' "$PR_JSON_PATH")"
+            if [ -n "$PR_TITLE" ]; then
+              printf -- '- [#%s %s](%s)\n' "$PR_NUMBER" "$PR_TITLE" "$PR_URL" >> "$PR_SUMMARY_PATH"
+            else
+              printf -- '- [#%s](%s)\n' "$PR_NUMBER" "$PR_URL" >> "$PR_SUMMARY_PATH"
+            fi
+            rm -f "$PR_JSON_PATH"
           done
 
           {
@@ -150,6 +162,8 @@ jobs:
             echo "issue_ids_path=${ISSUE_IDS_PATH}"
             echo "featureos_urls_path=${FEATUREOS_URLS_PATH}"
             echo "github_pr_urls_path=${GITHUB_PR_URLS_PATH}"
+            echo "pr_summary_path=${PR_SUMMARY_PATH}"
+            echo "log_path=${LOG_PATH}"
             echo "issue_count=$(wc -l < "$ISSUE_IDS_PATH" | tr -d ' ')"
             echo "featureos_url_count=$(wc -l < "$FEATUREOS_URLS_PATH" | tr -d ' ')"
             echo "github_pr_url_count=$(wc -l < "$GITHUB_PR_URLS_PATH" | tr -d ' ')"
@@ -181,6 +195,8 @@ jobs:
           ISSUE_IDS_PATH: ${{ steps.issues.outputs.issue_ids_path }}
           FEATUREOS_URLS_PATH: ${{ steps.issues.outputs.featureos_urls_path }}
           GITHUB_PR_URLS_PATH: ${{ steps.issues.outputs.github_pr_urls_path }}
+          PR_SUMMARY_PATH: ${{ steps.issues.outputs.pr_summary_path }}
+          LOG_PATH: ${{ steps.issues.outputs.log_path }}
         run: node .github/scripts/sync-linear-release.mjs
 
       - name: Summarize Linear release