@redpanda-data/docs-extensions-and-macros 5.56.1 → 5.58.0

package/tools/property-extractor/README.adoc

@@ -1223,7 +1223,7 @@ npm test -- --coverage
 ==== The live overrides corpus
 
 `__tests__/tools/property-extractor/property-corpus-rendering.test.js` runs the real
-overrides file, not a fixture, because a fixture passes while the live 438-entry corpus
+overrides file, not a fixture, because a fixture passes while the live overrides corpus
 breaks. Two files feed it, both mirrors of the `docs` repo:
 
 `__tests__/docs-data/property-overrides.json`:: A byte copy of `docs-data/property-overrides.json`.
@@ -1245,7 +1245,9 @@ test, so it sat three months and 114 entries behind. That test now has its own
 `property-overrides-admin-fixture.json`; put new fixture data there or in the test
 itself, never in the mirror.
 
-Refresh both from a `docs` checkout:
+Every Monday, `.github/workflows/property-corpus-drift.yml` compares both files against `docs` main. When they have drifted, it runs the recipe below and opens or updates one pull request from `bot/refresh-property-corpus`. If that PR's tests fail, the refresh has exposed a real bug: push the fix to the same branch, and while the PR is open the job stops updating the branch once its latest commit isn't the bot's.
+
+To refresh by hand, for example between weekly runs, run the same recipe from a `docs` checkout:
 
 [,bash]
 ----

package/tools/redpanda-connect/AUTOMATION.md

@@ -169,7 +169,8 @@ For each version pair `(oldVersion → newVersion)`:
     "removedFields": 2,       // Breaking changes!
     "deprecatedComponents": 0,
     "deprecatedFields": 1,
-    "changedDefaults": 0
+    "changedDefaults": 0,     // A default changed or was removed (breaking)
+    "documentedDefaults": 0   // A field with no default now states one (informational)
   },
   "details": {
     "newComponents": [
@@ -385,7 +386,8 @@ Changes between two consecutive versions:
     "newFields": [...],
     "removedFields": [...],
     "deprecatedFields": [...],
-    "changedDefaults": [...]
+    "changedDefaults": [...],
+    "documentedDefaults": [...]
   },
   "binaryAnalysis": {
     "versions": {

package/tools/redpanda-connect/multi-version-summary.js

@@ -63,7 +63,8 @@ function createMasterDiff(intermediateResults, finalDiffPath, outputPath) {
     removedFields: releases.reduce((sum, r) => sum + (r.summary.removedFields || 0), 0),
     deprecatedComponents: releases.reduce((sum, r) => sum + (r.summary.deprecatedComponents || 0), 0),
     deprecatedFields: releases.reduce((sum, r) => sum + (r.summary.deprecatedFields || 0), 0),
-    changedDefaults: releases.reduce((sum, r) => sum + (r.summary.changedDefaults || 0), 0)
+    changedDefaults: releases.reduce((sum, r) => sum + (r.summary.changedDefaults || 0), 0),
+    documentedDefaults: releases.reduce((sum, r) => sum + (r.summary.documentedDefaults || 0), 0)
   };
 
   const masterDiff = {

package/tools/redpanda-connect/pr-summary-formatter.js

@@ -3,6 +3,16 @@
  * Outputs a console-parseable format for GitHub Actions
  */
 
+/**
+ * Format a field default for the Markdown PR summary. A field with no default
+ * is `undefined`; a declared null default (Default(nil)) is a value.
+ * @param {*} value - The default, or undefined when the field has none
+ * @returns {string} Inline code, or `_no default_`
+ */
+function formatDefault(value) {
+  return value === undefined ? '_no default_' : `\`${JSON.stringify(value)}\``;
+}
+
 /**
  * Render Bloblang changes section for PR summary
  * @param {object} data - Bloblang change data
@@ -238,6 +248,9 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
   if (total.changedDefaults > 0) {
     lines.push(`- **${total.changedDefaults}** changed default values`);
   }
+  if (total.documentedDefaults > 0) {
+    lines.push(`- **${total.documentedDefaults}** newly stated default values`);
+  }
   if (total.newBloblangMethods > 0) {
     lines.push(`- **${total.newBloblangMethods}** new Bloblang methods`);
   }
@@ -375,12 +388,25 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
       lines.push('| Component | Field | Old Default | New Default |');
       lines.push('|-----------|-------|-------------|-------------|');
       changedDefaults.forEach(change => {
-        const oldVal = change.oldDefault !== undefined ? `\`${JSON.stringify(change.oldDefault)}\`` : '_none_';
-        const newVal = change.newDefault !== undefined ? `\`${JSON.stringify(change.newDefault)}\`` : '_none_';
+        const oldVal = formatDefault(change.oldDefault);
+        const newVal = formatDefault(change.newDefault);
         lines.push(`| \`${change.component}\` | \`${change.field}\` | ${oldVal} | ${newVal} |`);
       });
       lines.push('');
     }
+
+    // Fields that gained a stated default
+    const documentedDefaults = details.documentedDefaults || [];
+    if (documentedDefaults.length > 0) {
+      lines.push(`**Newly Stated Defaults (${documentedDefaults.length}):**`);
+      lines.push('');
+      lines.push("_These fields now state a default. They usually behaved this way already, so they are not listed as changes in What's new. Check that none of them changed behavior._");
+      lines.push('');
+      documentedDefaults.forEach(change => {
+        lines.push(`- \`${change.component}.${change.field}\`: ${formatDefault(change.newDefault)}`);
+      });
+      lines.push('');
+    }
   }
 
   // Writer action items (aggregate)
@@ -558,9 +584,9 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     lines.push('**Review Changed Defaults for Breaking Changes:**');
     lines.push('');
     allChangedDefaults.forEach(change => {
-      const oldVal = change.oldDefault !== undefined ? JSON.stringify(change.oldDefault) : 'none';
-      const newVal = change.newDefault !== undefined ? JSON.stringify(change.newDefault) : 'none';
-      lines.push(`- [ ] \`${change.component}.${change.field}\`: \`${oldVal}\` → \`${newVal}\` — changed in **${change.version}**`);
+      const oldVal = formatDefault(change.oldDefault);
+      const newVal = formatDefault(change.newDefault);
+      lines.push(`- [ ] \`${change.component}.${change.field}\`: ${oldVal} → ${newVal} — changed in **${change.version}**`);
     });
     lines.push('');
   }
@@ -717,6 +743,10 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
     lines.push(`- **${stats.changedDefaults}** default value change${stats.changedDefaults !== 1 ? 's' : ''}`);
   }
 
+  if (stats.documentedDefaults > 0) {
+    lines.push(`- **${stats.documentedDefaults}** newly stated default value${stats.documentedDefaults !== 1 ? 's' : ''} (no behavior change expected)`);
+  }
+
   lines.push('');
 
   // Writer Reminder for Commercial Names
@@ -1233,14 +1263,25 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
       const [type, name] = component.split(':');
       lines.push(`**${type}/${name}:**`);
       changes.forEach(c => {
-        const oldStr = JSON.stringify(c.oldDefault);
-        const newStr = JSON.stringify(c.newDefault);
-        lines.push(`- \`${c.field}\`: ${oldStr} → ${newStr}`);
+        lines.push(`- \`${c.field}\`: ${formatDefault(c.oldDefault)} → ${formatDefault(c.newDefault)}`);
       });
       lines.push('');
     });
   }
 
+  // Newly stated defaults
+  const documentedDefaults = diffData.details.documentedDefaults || [];
+  if (documentedDefaults.length > 0) {
+    lines.push('#### Newly Stated Defaults');
+    lines.push('');
+    lines.push("_These fields now state a default. They usually behaved this way already, so they are not listed as changes in What's new. Check that none of them changed behavior._");
+    lines.push('');
+    documentedDefaults.forEach(c => {
+      lines.push(`- \`${c.component}.${c.field}\`: ${formatDefault(c.newDefault)}`);
+    });
+    lines.push('');
+  }
+
   // New Bloblang Methods
   if (stats.newBloblangMethods > 0 && diffData.details.newBloblangMethods) {
     lines.push('#### New Bloblang Methods');

package/tools/redpanda-connect/report-delta.js

@@ -175,6 +175,10 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
   const deprecatedFields = [];
   // Changed default values
   const changedDefaults = [];
+  // Fields that had no default and now state one. The field behaved the same
+  // way before, the spec just didn't say so, so these are not default changes
+  // and stay out of What's new and the breaking-change warning.
+  const documentedDefaults = [];
 
   Object.keys(newMap).forEach(cKey => {
     if (!(cKey in oldMap)) return;
@@ -209,14 +213,16 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
         const newDefaultStr = JSON.stringify(newDefault);
 
         if (oldDefaultStr !== newDefaultStr) {
-          changedDefaults.push({
+          const entry = {
             component: cKey,
             field: fName,
             oldDefault: oldDefault,
             newDefault: newDefault,
             description: newFieldObj && newFieldObj.description,
             shortDescription: newFieldObj && newFieldObj.short_description
-          });
+          };
+          if (oldDefault === undefined) documentedDefaults.push(entry);
+          else changedDefaults.push(entry);
         }
       }
     });
@@ -280,6 +286,7 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       deprecatedComponents: deprecatedComponents.length,
       deprecatedFields: deprecatedFields.length,
       changedDefaults: changedDefaults.length,
+      documentedDefaults: documentedDefaults.length,
       platformTransitions: platformTransitions.length,
       newBloblangMethods: newBloblangMethods.length,
       removedBloblangMethods: removedBloblangMethods.length,
@@ -296,6 +303,7 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       deprecatedComponents,
       deprecatedFields,
       changedDefaults,
+      documentedDefaults,
       platformTransitions,
       newBloblangMethods,
       removedBloblangMethods,
@@ -646,7 +654,8 @@ function printDeltaReport(oldIndex, newIndex, opts = {}) {
         const oldDefaultStr = JSON.stringify(oldDefault);
         const newDefaultStr = JSON.stringify(newDefault);
 
-        if (oldDefaultStr !== newDefaultStr) {
+        // A field that had no default and now states one is not a change.
+        if (oldDefaultStr !== newDefaultStr && oldDefault !== undefined) {
           changedDefaultsList.push({
             component: cKey,
             field: fName,
@@ -719,8 +728,8 @@ function printDeltaReport(oldIndex, newIndex, opts = {}) {
     console.log('➤ Changed default values:');
     changedDefaultsList.forEach(entry => {
       const { component, field, oldDefault, newDefault } = entry;
-      const oldStr = JSON.stringify(oldDefault);
-      const newStr = JSON.stringify(newDefault);
+      const oldStr = oldDefault === undefined ? 'no default' : JSON.stringify(oldDefault);
+      const newStr = newDefault === undefined ? 'no default' : JSON.stringify(newDefault);
       console.log(`   • ${component} → ${field}`);
       console.log(`     Old: ${oldStr}`);
       console.log(`     New: ${newStr}`);

package/tools/redpanda-connect/rpcn-connector-docs-handler.js

@@ -657,7 +657,8 @@ function buildChangedDefaultsTable (changedDefaults, capFn) {
   const byFieldAndDefaults = {}
   for (const change of changedDefaults) {
     const [type, compName] = change.component.split(':')
-    const compositeKey = `${change.field}|${String(change.oldDefault)}|${String(change.newDefault)}`
+    // JSON keeps null apart from "null" and one object default apart from another.
+    const compositeKey = JSON.stringify([change.field, change.oldDefault, change.newDefault])
     if (!byFieldAndDefaults[compositeKey]) {
       byFieldAndDefaults[compositeKey] = {
         field: change.field,
@@ -675,23 +676,31 @@ function buildChangedDefaultsTable (changedDefaults, capFn) {
   section += '|Field |Old default |New default |Description |Affected components\n\n'
 
   for (const [, info] of Object.entries(byFieldAndDefaults)) {
-    // Values render as literal inline code, so interpolations like
-    // ${!uuid_v4()} and characters like * or _ show as typed.
     // Values render as literal inline code through pass:c, which, unlike
     // `+...+`, also keeps values with ++ or with spaces at either end. Strings
     // that are empty, start or end with whitespace, or contain a newline show
     // as JSON, so " " and "\n" read as the values they are.
-    const formatDefault = (val) => {
-      if (val === undefined || val === null) return 'none'
+    const formatDefault = (val, asJson = false) => {
+      // 'none' would read as a value, and is one for some fields (compression).
+      if (val === undefined) return '_no default_'
       let text
-      if (typeof val === 'string') text = (val === '' || /^\s|\s$|\n/.test(val)) ? JSON.stringify(val) : val
+      if (asJson) text = JSON.stringify(val)
+      // A null default is declared (Default(nil)), so it renders as a value.
+      else if (val === null) text = 'null'
+      else if (typeof val === 'string') text = (val === '' || /^\s|\s$|\n/.test(val)) ? JSON.stringify(val) : val
       else if (typeof val === 'number' || typeof val === 'boolean') text = String(val)
       else text = JSON.stringify(val)
       return `\`pass:c[${text.replace(/\]/g, '\\]').replace(/\|/g, '\\|')}]\``
     }
 
-    const oldVal = formatDefault(info.oldDefault)
-    const newVal = formatDefault(info.newDefault)
+    let oldVal = formatDefault(info.oldDefault)
+    let newVal = formatDefault(info.newDefault)
+    // A type change such as "5" to 5 or "null" to null would read as no
+    // change, so show both sides as JSON.
+    if (oldVal === newVal) {
+      oldVal = formatDefault(info.oldDefault, true)
+      newVal = formatDefault(info.newDefault, true)
+    }
     // A | in the description would end the cell and shift the row.
     const desc = info.description ? capFn(info.description).replace(/\|/g, '\\|') : '// TODO: Add description'
 

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,
+};