@redpanda-data/docs-extensions-and-macros 5.56.0 → 5.57.0

package/bin/doc-tools.js

@@ -2132,6 +2132,11 @@ automation
  * bullets — it is a CANDIDATE for the curation step that rewrites voice, adds
  * `Area::` labels, normalizes units, and phrases CVEs.
  *
+ * In phase 1, a backticked name that matches a property in the release
+ * series' redpanda-properties-<tag>.json becomes a `prop:<name>[link=true]` link. The
+ * file is found in modules/reference/attachments/ unless --properties-file
+ * names one. With no file, names stay monospace and a warning is logged.
+ *
  * @why
  * Release notes are the one reference surface whose source of truth is
  * engineer-authored prose rather than code, so the deterministic part
@@ -2164,6 +2169,7 @@ automation
   .option('--section-file <file>', 'Phase 2: a curated section (from the sm-release-notes skill) to insert (relative to repo root, must stay inside the repository)')
   .option('--date <date>', 'Authored release date as YYYY-MM-DD (required with --body; confirmed on the PR)')
   .option('--page <file>', 'Target release-notes page (relative to repo root, must stay inside the repository)', 'modules/reference/pages/releases/redpanda.adoc')
+  .option('--properties-file <file>', 'Phase 1: property JSON whose names become prop: links (relative to repo root, must stay inside the repository). Default: the newest redpanda-properties-<tag>.json in modules/reference/attachments/ for the tag\'s release series')
   .option('--section-only', 'Phase 1 only: print the candidate section and do not read or modify the page')
   .option('--dry-run', 'Print output to stdout instead of writing the page')
   .action(async (options) => {
@@ -2172,6 +2178,11 @@ automation
       buildReleaseSection,
       isGaTag,
     } = require('../tools/redpanda-release-notes/generate-release-notes.js')
+    const {
+      ATTACHMENTS_DIR,
+      findPropertiesFile,
+      loadPropertyNames,
+    } = require('../tools/redpanda-release-notes/property-names.js')
     try {
       const repoRoot = findRepoRoot()
 
@@ -2192,6 +2203,19 @@ automation
         return abs
       }
 
+      // Phase 1 links known property names. An explicit --properties-file must
+      // exist; a missing default only means names stay monospace.
+      const readPropertyNames = () => {
+        const file = options.propertiesFile
+          ? readInside(options.propertiesFile, '--properties-file')
+          : findPropertiesFile(path.join(repoRoot, ATTACHMENTS_DIR), options.tag)
+        if (!file) {
+          console.warn(`[release-notes] WARN: no property file for ${options.tag} in ${ATTACHMENTS_DIR}; property names stay monospace.`)
+          return undefined
+        }
+        return loadPropertyNames(file)
+      }
+
       // Phase-1 candidate preview: emit the candidate for the curation step. No
       // page is read or written — this is the LLM step's input, nothing else.
       if (options.sectionOnly) {
@@ -2203,7 +2227,9 @@ automation
           return
         }
         const body = fs.readFileSync(readInside(options.body, '--body'), 'utf8')
-        const section = buildReleaseSection({ body, version: options.tag, date: options.date })
+        const section = buildReleaseSection({
+          body, version: options.tag, date: options.date, propertyNames: readPropertyNames(),
+        })
         process.stdout.write(section)
         return
       }
@@ -2213,6 +2239,7 @@ automation
       const genArgs = { tag: options.tag, date: options.date, pageContent }
       if (hasBody) {
         genArgs.body = fs.readFileSync(readInside(options.body, '--body'), 'utf8')
+        genArgs.propertyNames = readPropertyNames()
       } else {
         genArgs.section = fs.readFileSync(readInside(options.sectionFile, '--section-file'), 'utf8')
       }
@@ -3055,9 +3082,10 @@ programCli
   .requiredOption('--repo <path>', 'Path to a Redpanda core checkout. Nothing is cloned.')
   .requiredOption('--diff <base>', 'Base ref: changes in <base>...HEAD are inspected')
   .option('--format <format>', 'Output format: json or human', 'json')
+  .option('--exclude <file>', 'File of already-dispatched findings, one "name change_kind" per line, to leave out of the report')
   .action((options) => {
     const { spawnSync } = require('child_process')
-    const { detectGatingChanges, buildDocImpact, enterprisePropertyNames, ENUM_HEADER, CONFIG_HEADER, CONFIG_SOURCE } = require('../tools/enterprise-features/detect-gating-changes')
+    const { detectGatingChanges, buildDocImpact, withoutSent, enterprisePropertyNames, ENUM_HEADER, CONFIG_HEADER, CONFIG_SOURCE } = require('../tools/enterprise-features/detect-gating-changes')
     const empty = { findings: [] }
     const result = spawnSync('git', ['diff', '--no-color', '--no-ext-diff', `${options.diff}...HEAD`, '--', ENUM_HEADER, CONFIG_HEADER, CONFIG_SOURCE], {
       cwd: options.repo, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024
@@ -3072,7 +3100,14 @@ programCli
     const header = spawnSync('git', ['show', `HEAD:${CONFIG_HEADER}`], { cwd: options.repo, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
     if (header.status !== 0) console.error(`git show HEAD:${CONFIG_HEADER} failed in ${options.repo}; configuration.cc changes are not checked: ${(header.stderr || '').trim()}`)
     const enterpriseNames = header.status === 0 ? enterprisePropertyNames(header.stdout) : []
-    const findings = detectGatingChanges(result.stdout, { enterpriseNames })
+    let findings = detectGatingChanges(result.stdout, { enterpriseNames })
+    if (options.exclude) {
+      try {
+        findings = withoutSent(findings, fs.readFileSync(options.exclude, 'utf8'))
+      } catch (err) {
+        console.error(`Could not read ${options.exclude}; nothing excluded: ${err.message}`)
+      }
+    }
     const report = buildDocImpact(findings) || empty
     if (options.format === 'human') {
       if (findings.length === 0) { console.log('No enterprise gating changes.'); return }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.56.0",
+  "version": "5.57.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/enterprise-features/detect-gating-changes.js

@@ -26,10 +26,13 @@
  * so a test can hand it a saved patch; the CLI wrapper runs git.
  *
  * Detection is by added and removed lines, paired by name, so a value that
- * merely moves within the enum is not reported. Both signals the header
- * carries for an enum value are used (the member line inside the enum, and
- * the `case license_required_feature::<name>:` line in format_to), so a
- * hunk header that happens not to name the enum still detects.
+ * merely moves within the enum is not reported. Only the member line inside
+ * the enum counts; `case license_required_feature::<name>:` labels are
+ * ignored, because they move whenever the formatter is rewritten.
+ *
+ * Not covered: node properties (src/v/config/node_config.h, where
+ * `fips_mode` is gated) are not scanned, and a restricted value that names a
+ * constant defined elsewhere is not seen (see restrictedValueChanges).
  *
  * Each finding names ONE affected page, the licensing overview. The docs-site
  * receiver falls back to matching a finding with no name match against open
@@ -54,15 +57,20 @@ const REGISTRY_URL = 'https://github.com/redpanda-data/docs/blob/main/shared/mod
 function splitFiles (diffText) {
   const files = []
   let current = null
+  let inHunk = false
   for (const raw of String(diffText || '').split('\n')) {
     const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(raw)
     if (m) {
       current = { path: m[2], lines: [] }
       files.push(current)
+      inHunk = false
       continue
     }
     if (!current) continue
-    if (/^(\+\+\+|---|index |new file|deleted file|similarity|rename|old mode|new mode)/.test(raw)) continue
+    // File header lines come before the first hunk. Inside a hunk, a removed
+    // `--x;` or an added `++x;` reads as `---x;` or `+++x;` and is content.
+    if (raw.startsWith('@@')) inHunk = true
+    if (!inHunk && /^(\+\+\+|---|index |new file|deleted file|similarity|rename|old mode|new mode)/.test(raw)) continue
     current.lines.push(raw)
   }
   return files
@@ -92,7 +100,7 @@ function enumChanges (lines) {
     const sign = line[0]
     if (sign !== '+' && sign !== '-') continue
     const target = sign === '+' ? added : removed
-    const member = inEnum && /^\s*([a-z][a-z0-9_]*)\s*,?\s*(\/\/.*)?$/.exec(body)
+    const member = inEnum && /^\s*([a-z][a-z0-9_]*)\s*(?:=\s*[^,/]+?)?\s*,?\s*(\/\/.*)?$/.exec(body)
     if (member) target.add(member[1])
   }
   return {
@@ -107,6 +115,8 @@ function enumChanges (lines) {
 // at a `;`, and also at a brace, an access specifier or a preprocessor line,
 // so a declaration never absorbs the line before it.
 const ENTERPRISE_DECL = /^\s*(?:config::)?enterprise<[\s\S]*>\s*([a-z][a-z0-9_]*)\s*;\s*$/
+// Any templated member declaration, wrapped or not (`property<bool> x;`).
+const ANY_DECL = /^\s*[\w:]+<[\s\S]*>\s*([a-z][a-z0-9_]*)\s*;\s*$/
 
 // Comments and attributes are dropped before joining: a `/* ... */` or
 // `[[attr]]` line above a declaration has no `;` or brace, so it would
@@ -186,24 +196,29 @@ function enterprisePropertyNames (headerText) {
  * configuration.h. A declaration changed in place shows as a -/+ pair with
  * the same name; the wrapper is on exactly one side. Each side of each hunk
  * (context plus its own changed lines) is joined into statements, so a
- * declaration that wraps across lines is read whole.
- * @returns {{added: string[], removed: string[]}}
+ * declaration that wraps across lines is read whole. A wrapped declaration
+ * that is removed and declared nowhere on the new side, wrapped or not, is
+ * `deleted`: the property is gone, not ungated.
+ * @returns {{added: string[], removed: string[], deleted: string[]}}
  */
 function enterprisePropertyChanges (lines) {
   const added = new Set()
   const removed = new Set()
-  const collect = (side, target) => {
+  const declaredNew = new Set()
+  const collect = (side, target, declared) => {
     for (const st of joinStatements(side)) {
       if (!st.changed) continue
       const m = ENTERPRISE_DECL.exec(st.text)
       if (m) target.add(m[1])
+      const any = declared && ANY_DECL.exec(st.text)
+      if (any) declared.add(any[1])
     }
   }
   let oldSide = []
   let newSide = []
   const flushHunk = () => {
     collect(oldSide, removed)
-    collect(newSide, added)
+    collect(newSide, added, declaredNew)
     oldSide = []
     newSide = []
   }
@@ -216,9 +231,11 @@ function enterprisePropertyChanges (lines) {
     else if (sign === ' ') { oldSide.push({ text }); newSide.push({ text }) }
   }
   flushHunk()
+  const gone = [...removed].filter((n) => !added.has(n))
   return {
     added: [...added].filter((n) => !removed.has(n)).sort(),
-    removed: [...removed].filter((n) => !added.has(n)).sort()
+    removed: gone.filter((n) => declaredNew.has(n)).sort(),
+    deleted: gone.filter((n) => !declaredNew.has(n)).sort()
   }
 }
 
@@ -253,6 +270,14 @@ function restrictedValueChanges (lines, enterpriseNames) {
     const body = line.slice(1)
     const opens = /^\s*,\s*([a-z][a-z0-9_]*)\s*\(/.exec(body)
     if (opens) { init = opens[1]; changed = false; continue }
+    // `*this, <value>, "name",` on one line carries the whole restricted
+    // argument list.
+    const oneLine = /^\s*\*this\s*,.*"([a-z][a-z0-9_]*)"\s*,/.exec(body)
+    if (oneLine && enterpriseNames.has(oneLine[1])) {
+      if (sign !== ' ') found.add(oneLine[1])
+      changed = false
+      continue
+    }
     if (/^\s*\*this\s*,/.test(body)) { changed = sign !== ' '; continue }
     // The name literal closes the restricted arguments. A string literal
     // that is neither this initializer's name nor an enterprise property
@@ -307,7 +332,7 @@ function detectGatingChanges (diffText, { enterpriseNames = [] } = {}) {
         })
       }
     } else if (file.path === CONFIG_HEADER) {
-      const { added, removed } = enterprisePropertyChanges(file.lines)
+      const { added, removed, deleted } = enterprisePropertyChanges(file.lines)
       for (const name of added) {
         findings.push({
           surface: 'enterprise-property',
@@ -326,6 +351,15 @@ function detectGatingChanges (diffText, { enterpriseNames = [] } = {}) {
           summary: `\`${name}\` is no longer wrapped in \`config::enterprise<>\` in \`${CONFIG_HEADER}\`, so it no longer needs a license. The registry entry that names it (${REGISTRY_URL}) and its row on ${DISABLE_PAGE} need to change.`
         })
       }
+      for (const name of deleted) {
+        findings.push({
+          surface: 'enterprise-property',
+          name,
+          change_kind: 'enterprise-property-removed',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `\`${name}\`, a \`config::enterprise<>\` property, was removed from \`${CONFIG_HEADER}\`. From the first release that contains this change the property no longer exists, so its row on ${DISABLE_PAGE} goes and the registry entry that names it (${REGISTRY_URL}) needs a new source pointer or a note, never deletion: a published external name stays in the registry.`
+        })
+      }
     } else if (file.path === CONFIG_SOURCE) {
       // A property whose wrapper changed in the header is already reported
       // above; its initializer changes with it.
@@ -344,6 +378,18 @@ function detectGatingChanges (diffText, { enterpriseNames = [] } = {}) {
   return findings
 }
 
+/**
+ * Drop findings already dispatched for this PR. `sent` is the text of the
+ * review state's dispatched-gating.txt: one `name change_kind` key per line.
+ * Filtering here, before buildDocImpact, keeps the ticket title and body to
+ * the findings that remain, and lets an eleventh finding in once the first
+ * ten are sent.
+ */
+function withoutSent (findings, sent) {
+  const done = new Set(String(sent || '').split('\n').map((l) => l.trim()).filter(Boolean))
+  return findings.filter((f) => !done.has(`${f.name} ${f.change_kind}`))
+}
+
 /**
  * Shape findings as the doc-impact report the review workflow dispatches
  * (the same JSON the model writes to doc-impact.json), or null when there is
@@ -385,6 +431,7 @@ module.exports = {
   CONFIG_SOURCE,
   detectGatingChanges,
   buildDocImpact,
+  withoutSent,
   enumChanges,
   enterprisePropertyChanges,
   enterprisePropertyNames,

package/tools/redpanda-release-notes/generate-release-notes.js

@@ -132,48 +132,90 @@ function insertReleaseSection(pageContent, sectionText) {
 }
 
 /**
- * Reorders the entries within each `=== category` of a curated section so that
- * entries sharing an `Area::` label sit together. Areas are ordered
- * ALPHABETICALLY (case-insensitive), so a given area sits in the same place on
- * every release instead of moving with the source's merge order; entries keep
- * their source order within an area, so the sort is stable. The label is
- * repeated per entry (not merged into one heading), so the page format is
- * unchanged — only the order of entries within a category changes. Running it on
- * an already-clustered section is a no-op, so it is safe to apply on every
- * release and on a backfill.
+ * Groups the entries within each `=== category` of a curated section by their
+ * `Area::` label. Areas are ordered ALPHABETICALLY (case-insensitive), so a given
+ * area sits in the same place on every release instead of moving with the
+ * source's merge order; entries keep their source order within an area, so the
+ * sort is stable. Each area is written ONCE per category, as the definition-list
+ * term, with its entries as a bulleted list under it:
  *
- * Only the clean single-line `Area:: description` definition-list form is
- * reordered. A category whose entries are not all of that form — a phase-1
- * candidate's plain `*` bullets, or a multi-line entry — is left in its original
- * order, so this is a safe no-op on anything it does not recognize. A curated
- * category (one with at least one `Area::` entry) that bails logs a warning, since
- * it then ships unclustered. Area keys are trimmed for grouping, so `Kafka API`
- * and `Kafka API ` are one area. Headings and any prose outside a category are
- * passed through untouched.
+ *   Cloud Topics::
+ *   * First entry.
+ *   * Second entry.
+ *
+ * An area with one entry still gets a one-item list. Input entries may be in
+ * either form: single-line `Area:: description` (what curation writes) or an
+ * already-grouped `Area::` paragraph with single-line `* ` items. A category can
+ * mix the two. Running it on its own output is a no-op, so it is safe to apply on
+ * every release, on a backfill, and on a section grouped by hand.
+ *
+ * A category with any other kind of entry (a phase-1 candidate's plain `*`
+ * bullets, or a multi-line entry) is not grouped, so this is a safe no-op on
+ * anything it does not recognize. Its entries keep their order and text. The
+ * one change is that single-line entries on adjacent lines come out with a
+ * blank line between them, which AsciiDoc renders the same way. Line endings
+ * in the output are LF. A curated category (one with at least
+ * one `Area::` entry) that is left as it is logs a warning, because it then
+ * ships ungrouped. Area keys are trimmed, so `Kafka API` and `Kafka API ` are one
+ * area, written as the trimmed label. Headings and any prose outside a category
+ * are passed through untouched.
  *
  * @param {string} sectionText - A rendered release section.
- * @return {string} The section with each category's entries clustered by area,
+ * @return {string} The section with each category's entries grouped by area,
  *   ending in a single newline.
  */
 function clusterSectionByArea(sectionText) {
-  // The area label is the text up to the first `:: ` (double-colon + space),
-  // which is the AsciiDoc definition-list term separator. A lazy match stops at
-  // that first separator, so a `::` later in the description is left alone. A
-  // leading list marker (`*`, `-`, `.`), at column zero or indented, is rejected
-  // so a plain bullet that happens to carry a `::` — a phase-1 candidate line —
-  // is not mistaken for an area entry; its category then bails and is left
-  // untouched.
-  const ENTRY_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s/;
+  // A single-line entry: the area label is the text up to the first `:: `
+  // (double-colon + space), the AsciiDoc definition-list term separator. A lazy
+  // match stops at that first separator, so a `::` later in the description is
+  // left alone. A leading list marker (`*`, `-`, `.`), at column zero or
+  // indented, is rejected so a plain bullet that happens to carry a `::` (a
+  // phase-1 candidate line) is not mistaken for an area entry.
+  const ENTRY_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s+(\S.*)$/;
+  // A grouped area: a term line with nothing after the `::`.
+  const TERM_RE = /^(?!\s*[*.\-]+\s)(.+?)::\s*$/;
+  // An item of a grouped area: one `* ` bullet on one line.
+  const ITEM_RE = /^\* (\S.*)$/;
+
+  // Parses one paragraph into [area, items], or null if it is not a recognized
+  // entry. A grouped paragraph must be a term line followed only by items.
+  const parseEntry = (para) => {
+    if (para.length === 1) {
+      const m = para[0].match(ENTRY_RE);
+      if (m) return [m[1].trim(), [m[2]]];
+    }
+    const t = para[0].match(TERM_RE);
+    if (t && para.length > 1) {
+      const items = [];
+      for (const line of para.slice(1)) {
+        const i = line.match(ITEM_RE);
+        if (!i) return null;
+        items.push(i[1]);
+      }
+      return [t[1].trim(), items];
+    }
+    return null;
+  };
+  const looksCurated = (para) => ENTRY_RE.test(para[0]) || TERM_RE.test(para[0]);
 
   // Tokenize into paragraphs: maximal runs of non-blank lines. In this format
-  // every heading and every entry is one such paragraph.
-  const lines = String(sectionText).replace(/\n+$/, '').split('\n');
+  // every heading, every single-line entry, and every grouped area is one such
+  // paragraph. Single-line entries on adjacent lines, with no blank line
+  // between them, are valid AsciiDoc too, so each one starts its own paragraph.
+  // A grouped area's term line does not match ENTRY_RE, so its bullets stay in
+  // one paragraph with it. CRLF and CR line endings become LF first: `.` in
+  // the patterns above does not match `\r`, so a CRLF line would match nothing.
+  const lines = String(sectionText).replace(/\r\n?/g, '\n').replace(/\n+$/, '').split('\n');
   const paragraphs = [];
   let current = [];
   for (const line of lines) {
     if (/^\s*$/.test(line)) {
       if (current.length) { paragraphs.push(current); current = []; }
     } else {
+      if (current.length === 1 && ENTRY_RE.test(current[0]) && ENTRY_RE.test(line)) {
+        paragraphs.push(current);
+        current = [];
+      }
       current.push(line);
     }
   }
@@ -181,38 +223,35 @@ function clusterSectionByArea(sectionText) {
 
   const out = [];
   let categoryEntries = null; // entry paragraphs of the open `=== category`
-  let categoryBail = false;   // the open category has an unrecognized entry
   let categoryTitle = '';     // the open category's heading text, for warnings
 
   const flushCategory = () => {
     if (!categoryEntries) return;
-    if (categoryBail) {
-      // A phase-1 bullet category is expected to bail. A curated one (it has at
-      // least one `Area::` entry) bailing means some entry spans several lines,
-      // so the whole category ships unclustered — say so rather than fail quietly.
-      if (categoryEntries.some((entry) => ENTRY_RE.test(entry[0]))) {
-        console.warn(`${LOG_TAG} WARN: "${categoryTitle}" not grouped by area: an entry is not a single-line \`Area:: description\` (for example a \`+\` continuation or a code block).`);
+    const parsed = categoryEntries.map(parseEntry);
+    if (parsed.some((e) => e === null)) {
+      // A phase-1 bullet category is expected to be left as it is. A curated one
+      // (it has at least one `Area::` entry) left as it is means some entry is
+      // neither form, so the whole category ships ungrouped. Say so rather than
+      // fail quietly.
+      if (categoryEntries.some(looksCurated)) {
+        console.warn(`${LOG_TAG} WARN: "${categoryTitle}" not grouped by area: an entry is neither a single-line \`Area:: description\` nor an \`Area::\` term with single-line \`* \` items (for example a \`+\` continuation or a code block).`);
       }
       for (const entry of categoryEntries) out.push(entry);
     } else {
       const order = [];
       const groups = new Map();
-      for (const entry of categoryEntries) {
-        // Trimmed, so a stray space before `::` does not split one area in two.
-        // Only the grouping key is trimmed; the entry text is emitted verbatim.
-        const key = entry[0].match(ENTRY_RE)[1].trim();
+      for (const [key, items] of parsed) {
         if (!groups.has(key)) { groups.set(key, []); order.push(key); }
-        groups.get(key).push(entry);
+        groups.get(key).push(...items);
       }
       // Areas alphabetical (case-insensitive), so an area lands in the same
       // place on every release; entries keep their source order within an area.
       order.sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
       for (const key of order) {
-        for (const entry of groups.get(key)) out.push(entry);
+        out.push([`${key}::`, ...groups.get(key).map((item) => `* ${item}`)]);
       }
     }
     categoryEntries = null;
-    categoryBail = false;
   };
 
   for (const para of paragraphs) {
@@ -222,7 +261,6 @@ function clusterSectionByArea(sectionText) {
       flushCategory();
       out.push(para);
       categoryEntries = [];
-      categoryBail = false;
       categoryTitle = first.replace(/^===\s+/, '').trim();
     } else if (/^==\s/.test(first)) {
       // The release heading (or any other top-level heading) closes the open
@@ -232,7 +270,6 @@ function clusterSectionByArea(sectionText) {
       categoryEntries = null;
     } else if (categoryEntries) {
       categoryEntries.push(para);
-      if (para.length !== 1 || !ENTRY_RE.test(para[0])) categoryBail = true;
     } else {
       // Prose outside any category (for example an intro paragraph): untouched.
       out.push(para);
@@ -250,10 +287,11 @@ function clusterSectionByArea(sectionText) {
  * @param {string} options.body - The raw rpchangelog release body markdown.
  * @param {string} options.version - The release version (`v26.2.3` or `26.2.3`).
  * @param {string} options.date - The release date as `YYYY-MM-DD`.
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros.
  * @return {string} The rendered AsciiDoc section.
  */
-function buildReleaseSection({ body, version, date }) {
-  const { sections } = parseReleaseBody(body);
+function buildReleaseSection({ body, version, date, propertyNames }) {
+  const { sections } = parseReleaseBody(body, { propertyNames });
   return renderReleaseSection({ version, date, sections });
 }
 
@@ -306,9 +344,10 @@ function assertSectionMatchesTag(section, version) {
  * @param {string} options.tag - The release tag (`v26.2.3`).
  * @param {string} [options.date] - The authored release date as `YYYY-MM-DD` (phase 1 only).
  * @param {string} options.pageContent - The current target page content.
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros (phase 1 only).
  * @return {{status: 'ok'|'skipped', reason?: string, section?: string, content?: string}}
  */
-function generateReleaseNotes({ body, section, tag, date, pageContent }) {
+function generateReleaseNotes({ body, section, tag, date, pageContent, propertyNames }) {
   if (body == null && section == null) {
     throw new Error('Provide either body (phase 1) or section (phase 2).');
   }
@@ -337,7 +376,7 @@ function generateReleaseNotes({ body, section, tag, date, pageContent }) {
     // have to, and so a hand-written section is normalized the same way.
     finalSection = clusterSectionByArea(section);
   } else {
-    finalSection = buildReleaseSection({ body, version, date });
+    finalSection = buildReleaseSection({ body, version, date, propertyNames });
   }
   const content = insertReleaseSection(pageContent, finalSection);
   return { status: 'ok', section: finalSection, content };

package/tools/redpanda-release-notes/parse-release-body.js

@@ -8,7 +8,8 @@
 //
 // This module does ONLY the deterministic, no-judgment work: split into
 // sections, join wrapped bullet lines, strip source noise, unescape backticks,
-// de-duplicate backport repeats, and normalize category order/case. It does NOT
+// link known configuration properties, de-duplicate backport repeats, and
+// normalize category order/case. It does NOT
 // rewrite voice, add `Area::` labels, normalize units, phrase CVEs, or drop
 // bodyless entries — those need editorial judgment and belong to the curation
 // step that runs on the generated page.
@@ -88,18 +89,43 @@ function stripLeadingIssueRef(text) {
  * the editorial curation step.
  *
  * @param {string} raw - The joined raw bullet text.
+ * @param {Object} [options]
+ * @param {Set<string>} [options.propertyNames] - Known property names to link (see linkProperties).
  * @return {string} The cleaned entry text.
  */
-function cleanEntry(raw) {
+function cleanEntry(raw, { propertyNames } = {}) {
   let text = raw.replace(/\s+/g, ' ').trim();
   text = stripLeadingIssueRef(text);
   text = stripAttribution(text);
   text = text.replace(/\\`/g, '`');
+  text = linkProperties(text, propertyNames);
   text = normalizeUnits(text);
   text = escapeAsciiDocBraces(text);
   return text.trim();
 }
 
+/**
+ * Rewrites a backticked configuration property name as a `prop:` macro with
+ * `link=true`, so the page links it to the property reference. Without
+ * `link=true`, the macro shows only a hover tooltip. Engineers cannot write `prop:` in
+ * the source, because nothing resolves it outside the docs build, so this is
+ * where the link is added.
+ *
+ * Only an exact match for a known name is rewritten: `` `retention.ms` `` is,
+ * `` `retention.ms=1000` `` and `` `health_manager` `` are not. A name with no
+ * `_` or `.` (such as `admin` or `rack`) is never rewritten, because in prose
+ * those words usually mean something other than the property.
+ *
+ * @param {string} text - The entry text, with backticks already unescaped.
+ * @param {Set<string>} [propertyNames] - Known property names. Without it, the text is returned unchanged.
+ * @return {string} The text with known property names as `prop:<name>[link=true]`.
+ */
+function linkProperties(text, propertyNames) {
+  if (!propertyNames || propertyNames.size === 0) return text;
+  return text.replace(/`([\w.-]+)`/g, (match, name) =>
+    /[_.]/.test(name) && propertyNames.has(name) ? `prop:${name}[link=true]` : match);
+}
+
 /**
  * Rewrites the source's underscore data-size notation to the readable unit the
  * standard requires (`4_MiB` -> `4 MiB`). Only a digit followed by `_` and a
@@ -131,11 +157,13 @@ function escapeAsciiDocBraces(text) {
  * grouped by canonical category in page order.
  *
  * @param {string} body - The raw GitHub Release body markdown.
+ * @param {Object} [options]
+ * @param {Set<string>} [options.propertyNames] - Known property names to link as `prop:` macros.
  * @return {{sections: Array<{kind: string, title: string, entries: string[]}>}}
  *   Sections in page order (Features, Bug fixes, Improvements); a category with
  *   no entries is omitted.
  */
-function parseReleaseBody(body) {
+function parseReleaseBody(body, { propertyNames } = {}) {
   if (typeof body !== 'string' || body.trim() === '') {
     throw new Error('Release body is empty.');
   }
@@ -155,7 +183,7 @@ function parseReleaseBody(body) {
 
   const flush = () => {
     if (current !== null && currentKind && buckets[currentKind]) {
-      const entry = cleanEntry(current);
+      const entry = cleanEntry(current, { propertyNames });
       if (entry) buckets[currentKind].push(entry);
     }
     current = null;
@@ -231,6 +259,7 @@ module.exports = {
   stripAttribution,
   stripLeadingIssueRef,
   cleanEntry,
+  linkProperties,
   normalizeUnits,
   escapeAsciiDocBraces,
   PAGE_ORDER,

package/tools/redpanda-release-notes/property-names.js

@@ -0,0 +1,65 @@
+// Load the configuration property names that the release-notes generator links
+// as `prop:` macros. The names come from the same redpanda-properties-<tag>.json
+// attachment that the prop macro validates against, so a name linked here is a
+// name the docs build can resolve.
+
+const fs = require('fs');
+const path = require('path');
+
+// The attachment directory, relative to the docs repository root.
+const ATTACHMENTS_DIR = 'modules/reference/attachments';
+const PROPERTIES_JSON_RX = /^redpanda-properties-v(\d+)\.(\d+)\.(\d+)\.json$/;
+
+/**
+ * Returns the property names in a parsed property JSON file.
+ *
+ * @param {Object} json - Parsed redpanda-properties-<tag>.json content.
+ * @return {Set<string>} The property names.
+ * @throws {Error} If the file has no `properties` object.
+ */
+function propertyNamesFromJson(json) {
+  if (!json || typeof json.properties !== 'object' || json.properties === null) {
+    throw new Error('Property file has no "properties" object.');
+  }
+  return new Set(Object.keys(json.properties));
+}
+
+/**
+ * Finds the newest GA property file for a tag's release series. A 26.2 tag
+ * uses 26.2 data only, the same rule the prop macro applies to a page, so a
+ * property from another release series is never linked.
+ *
+ * @param {string} dir - The directory to search.
+ * @param {string} tag - The release tag (`v26.2.5` or `26.2.5`).
+ * @return {string|null} The path to the newest matching file, or null if there is none.
+ */
+function findPropertiesFile(dir, tag) {
+  const m = String(tag).match(/^v?(\d+)\.(\d+)\./);
+  if (!m || !fs.existsSync(dir)) return null;
+  const [, major, minor] = m;
+  let best = null;
+  for (const file of fs.readdirSync(dir)) {
+    const f = file.match(PROPERTIES_JSON_RX);
+    if (!f || f[1] !== major || f[2] !== minor) continue;
+    const patch = Number(f[3]);
+    if (!best || patch > best.patch) best = { patch, file };
+  }
+  return best ? path.join(dir, best.file) : null;
+}
+
+/**
+ * Reads the property names from a property JSON file.
+ *
+ * @param {string} file - Path to a redpanda-properties-<tag>.json file.
+ * @return {Set<string>} The property names.
+ */
+function loadPropertyNames(file) {
+  return propertyNamesFromJson(JSON.parse(fs.readFileSync(file, 'utf8')));
+}
+
+module.exports = {
+  ATTACHMENTS_DIR,
+  propertyNamesFromJson,
+  findPropertiesFile,
+  loadPropertyNames,
+};