@redpanda-data/docs-extensions-and-macros 5.51.2 → 5.53.0

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

@@ -0,0 +1,241 @@
+// Parse a Self-Managed rpchangelog release body into a structured, de-noised model.
+//
+// Input is the raw GitHub Release body a release captain pastes into the
+// streaming-enterprise release (the output of `rpchangelog.py rel`): markdown
+// with `## Features` / `## Bug Fixes` / `## Improvements` sections, each a list
+// of `*` bullets carrying `by @author in [#PR](url)` suffixes and, sometimes,
+// a leading `[#issue](url)` reference.
+//
+// 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
+// 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.
+
+const LOG_TAG = '[release-notes]';
+
+// Canonical page order and headings: Features, then Bug fixes, then Improvements
+// (improvements last — they are usually internal detail, least relevant to a
+// reader scanning what changed). This matches rpchangelog's raw source order
+// (Features -> Bug Fixes -> Improvements), so the reorder only recases the
+// "Bug Fixes" heading. It deliberately differs from ADP, which puts fixes last.
+const KIND_FEATURE = 'feature';
+const KIND_IMPROVEMENT = 'improvement';
+const KIND_FIX = 'fix';
+
+const PAGE_ORDER = [KIND_FEATURE, KIND_FIX, KIND_IMPROVEMENT];
+const PAGE_TITLE = {
+  [KIND_FEATURE]: 'Features',
+  [KIND_IMPROVEMENT]: 'Improvements',
+  [KIND_FIX]: 'Bug fixes',
+};
+
+/**
+ * Maps a source `##` heading to a canonical kind by keyword, mirroring ADP's
+ * `sectionKind`. Returns null for a heading that is not one of the three
+ * release-note categories (for example rpchangelog's `--show-extra` `None` /
+ * `Unclear` sections), so the caller can ignore it.
+ *
+ * @param {string} heading - The heading text after the `##` marker.
+ * @return {string|null} One of the KIND_* constants, or null if unrecognized.
+ */
+function sectionKind(heading) {
+  const h = heading.toLowerCase();
+  if (h.includes('feature')) return KIND_FEATURE;
+  if (h.includes('improvement')) return KIND_IMPROVEMENT;
+  if (h.includes('fix')) return KIND_FIX;
+  return null;
+}
+
+/**
+ * Strips the trailing attribution blocks rpchangelog appends to every bullet:
+ * ` by @author` optionally followed by ` in [#PR](url)`, repeated once per PR
+ * when a change was aggregated from several PRs (the backport case). Works from
+ * the end of the string so it only ever removes trailing attribution, never a
+ * legitimate mid-sentence "by".
+ *
+ * @param {string} text - A single bullet's text.
+ * @return {string} The text with trailing attribution removed.
+ */
+function stripAttribution(text) {
+  const trailing = /\s+by\s+@[A-Za-z0-9][A-Za-z0-9._-]*(?:\s+in\s+\[#\d+\]\([^)]*\))?\s*$/i;
+  let out = text;
+  while (trailing.test(out)) {
+    out = out.replace(trailing, '');
+  }
+  return out;
+}
+
+/**
+ * Strips a leading `[#issue](url)` reference that rpchangelog prepends when a
+ * PR body declared `Fixes: #N`. Only the leading reference is removed; links
+ * inside the sentence are left alone.
+ *
+ * @param {string} text - A single bullet's text.
+ * @return {string} The text with a leading issue reference removed.
+ */
+function stripLeadingIssueRef(text) {
+  return text.replace(/^\s*\[#\d+\]\([^)]*\)\s+/, '');
+}
+
+/**
+ * Cleans one bullet: remove attribution and leading issue ref, unescape
+ * backslash-escaped backticks (`\`` -> `` ` ``) that survive from the PR body,
+ * collapse whitespace introduced by joining wrapped lines, and apply the two
+ * context-free mechanical normalizations — AsciiDoc brace escaping and the
+ * standard-mandated unit notation. House-style spelling and voice are left to
+ * the editorial curation step.
+ *
+ * @param {string} raw - The joined raw bullet text.
+ * @return {string} The cleaned entry text.
+ */
+function cleanEntry(raw) {
+  let text = raw.replace(/\s+/g, ' ').trim();
+  text = stripLeadingIssueRef(text);
+  text = stripAttribution(text);
+  text = text.replace(/\\`/g, '`');
+  text = normalizeUnits(text);
+  text = escapeAsciiDocBraces(text);
+  return text.trim();
+}
+
+/**
+ * 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
+ * size unit is touched, so identifiers such as `s3_fifo` or `last_offset_delta`
+ * are left alone.
+ *
+ * @param {string} text - The entry text.
+ * @return {string} The text with data-size units normalized.
+ */
+function normalizeUnits(text) {
+  return text.replace(/(\d)_((?:[KMGT]i?)?B)\b/g, '$1 $2');
+}
+
+/**
+ * Escapes AsciiDoc attribute-reference braces so a literal `{id}` in the source
+ * renders as text rather than an (empty) attribute substitution. Braces already
+ * escaped are left as-is. AsciiDoc substitutes attributes even inside inline
+ * monospace, so this applies everywhere in the entry, including within backticks.
+ *
+ * @param {string} text - The entry text.
+ * @return {string} The text with unescaped braces escaped.
+ */
+function escapeAsciiDocBraces(text) {
+  return text.replace(/(?<!\\)([{}])/g, '\\$1');
+}
+
+/**
+ * Parses a raw rpchangelog release body into de-noised, de-duplicated entries
+ * grouped by canonical category in page order.
+ *
+ * @param {string} body - The raw GitHub Release body markdown.
+ * @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) {
+  if (typeof body !== 'string' || body.trim() === '') {
+    throw new Error('Release body is empty.');
+  }
+
+  // Drop HTML comments up front (rpchangelog strips them from PR bodies, but a
+  // pasted body may still carry some).
+  const cleaned = body.replace(/<!--[\s\S]*?-->/g, '');
+
+  const buckets = {
+    [KIND_FEATURE]: [],
+    [KIND_IMPROVEMENT]: [],
+    [KIND_FIX]: [],
+  };
+
+  let currentKind = null; // kind of the section we are inside, or null to ignore
+  let current = null; // the bullet text being accumulated, or null between bullets
+
+  const flush = () => {
+    if (current !== null && currentKind && buckets[currentKind]) {
+      const entry = cleanEntry(current);
+      if (entry) buckets[currentKind].push(entry);
+    }
+    current = null;
+  };
+
+  const lines = cleaned.split(/\r?\n/);
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      currentKind = sectionKind(heading[1]);
+      continue;
+    }
+
+    // The changelog footer ends the release notes; nothing after it is an entry.
+    if (/^\s*\*\*(?:Partial|Full)\s+Changelog\*\*/i.test(line)) {
+      flush();
+      currentKind = null;
+      continue;
+    }
+
+    if (currentKind === null) continue;
+
+    const bullet = line.match(/^\s*[*-]\s+(.*)$/);
+    if (bullet) {
+      flush();
+      current = bullet[1];
+      continue;
+    }
+
+    if (line.trim() === '') {
+      // Blank line: entries in this format are contiguous, so a blank marks the
+      // end of the current bullet rather than a continuation.
+      flush();
+      continue;
+    }
+
+    // A non-blank, non-bullet line continues the current wrapped bullet.
+    if (current !== null) {
+      current += ' ' + line.trim();
+    }
+  }
+  flush();
+
+  const sections = [];
+  for (const kind of PAGE_ORDER) {
+    const seen = new Set();
+    const entries = [];
+    for (const entry of buckets[kind]) {
+      // De-duplicate backport repeats: the same change aggregated from several
+      // PRs yields identical text once attribution is stripped.
+      const key = entry.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      entries.push(entry);
+    }
+    if (entries.length > 0) {
+      sections.push({ kind, title: PAGE_TITLE[kind], entries });
+    }
+  }
+
+  if (sections.length === 0) {
+    console.warn(`${LOG_TAG} WARN: no Features/Improvements/Bug fixes entries found in the release body.`);
+  }
+
+  return { sections };
+}
+
+module.exports = {
+  parseReleaseBody,
+  // Exported for unit tests and reuse.
+  sectionKind,
+  stripAttribution,
+  stripLeadingIssueRef,
+  cleanEntry,
+  normalizeUnits,
+  escapeAsciiDocBraces,
+  PAGE_ORDER,
+  PAGE_TITLE,
+  KIND_FEATURE,
+  KIND_IMPROVEMENT,
+  KIND_FIX,
+};

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

@@ -0,0 +1,70 @@
+// Render a parsed release model into a candidate AsciiDoc release-notes section.
+//
+// Output is a `== vX.Y.Z (date)` section with `=== Features` / `=== Bug fixes`
+// / `=== Improvements` subsections of plain `*` bullets. Entries are emitted as
+// bullets carrying the de-noised source prose verbatim: this is a CANDIDATE for
+// the curation step, which rewrites voice, converts bullets to `Area::`
+// definition-list items, normalizes units, and phrases CVEs. This renderer adds
+// no `Area::` labels and makes no editorial change.
+
+const LOG_TAG = '[release-notes]';
+
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Normalizes a tag or version to a bare `X.Y.Z` (strips a leading `v`).
+ *
+ * @param {string} version - A version or tag, such as `v26.2.3` or `26.2.3`.
+ * @return {string} The bare `X.Y.Z` version.
+ */
+function normalizeVersion(version) {
+  return String(version || '').trim().replace(/^v/i, '');
+}
+
+/**
+ * Renders one release section as AsciiDoc.
+ *
+ * @param {Object} options
+ * @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` (authored; the
+ *   captain confirms it on the PR).
+ * @param {Array<{title: string, entries: string[]}>} options.sections - Sections
+ *   in page order, as produced by parseReleaseBody.
+ * @return {string} The AsciiDoc section, ending with a single trailing newline.
+ * @throws {Error} If the version or date is malformed, or there are no sections.
+ */
+function renderReleaseSection({ version, date, sections }) {
+  const v = normalizeVersion(version);
+  if (!VERSION_RE.test(v)) {
+    throw new Error(`Invalid version: ${JSON.stringify(version)}. Expected X.Y.Z (optionally v-prefixed).`);
+  }
+  if (!DATE_RE.test(String(date || '').trim())) {
+    throw new Error(`Invalid date: ${JSON.stringify(date)}. Expected YYYY-MM-DD.`);
+  }
+  if (!Array.isArray(sections) || sections.length === 0) {
+    throw new Error('No release-note sections to render.');
+  }
+
+  const lines = [`== v${v} (${String(date).trim()})`, ''];
+  for (const section of sections) {
+    if (!section.entries || section.entries.length === 0) continue;
+    lines.push(`=== ${section.title}`, '');
+    for (const entry of section.entries) {
+      lines.push(`* ${entry}`);
+    }
+    lines.push('');
+  }
+
+  // Trim the trailing blank line to exactly one terminating newline.
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.join('\n') + '\n';
+}
+
+module.exports = {
+  renderReleaseSection,
+  normalizeVersion,
+  VERSION_RE,
+  DATE_RE,
+  LOG_TAG,
+};

package/tools/rpk-docs/helpers/index.js

@@ -305,9 +305,9 @@ function isPluginCommand(commandPath, pluginVersions) {
 }
 
 /**
- * Convert ALL CAPS section name to title case for display
+ * Convert ALL CAPS section name to sentence case for display
  * @param {string} name - ALL CAPS section name
- * @returns {string} Title case name
+ * @returns {string} Sentence case name
  */
 function sectionTitle(name) {
   if (!name) return ''
@@ -317,18 +317,41 @@ function sectionTitle(name) {
     'id', 'ip', 'api', 'url', 'uri', 'cpu', 'gpu', 'ram', 'io',
     'tls', 'ssl', 'mtls', 'sasl', 'sso', 'oauth', 'oidc', 'jwt',
     'json', 'yaml', 'xml', 'csv', 'http', 'https', 'grpc', 'rpc',
-    'aws', 'gcp', 'azure', 's3', 'eos'
+    'aws', 'gcp', 's3', 'eos'
   ])
 
-  // Product names that should be title cased
+  // Proper nouns that keep their initial capital
   const properNouns = new Set([
-    'redpanda', 'kafka', 'kubernetes', 'schema', 'registry'
+    'redpanda', 'kafka', 'kubernetes', 'azure'
   ])
 
+  // Multi-word proper nouns, capitalized only as the full phrase
+  // ("SCHEMA REGISTRY" -> "Schema Registry", but "SCHEMA FORMAT" -> "Schema format")
+  const properPhrases = [['schema', 'registry']]
+
+  const capitalize = word => word.charAt(0).toUpperCase() + word.slice(1)
+
   // Split on spaces/hyphens but keep & as its own token
   // "PRODUCER ID & EPOCH" -> ["producer", "id", "&", "epoch"]
   const words = name.toLowerCase().split(/[\s-]+/)
 
+  const inPhrase = new Set()
+  for (const phrase of properPhrases) {
+    for (let i = 0; i + phrase.length <= words.length; i++) {
+      if (phrase.every((part, j) => words[i + j] === part)) {
+        phrase.forEach((_, j) => inPhrase.add(i + j))
+      }
+    }
+  }
+
+  // Sentence case: capitalize the first word, acronyms, and proper nouns;
+  // lowercase everything else
+  const formatPart = (part, isFirst, index) => {
+    if (acronyms.has(part)) return part.toUpperCase()
+    if (isFirst || properNouns.has(part) || inPhrase.has(index)) return capitalize(part)
+    return part
+  }
+
   return words.map((word, index) => {
     // Preserve ampersand as-is
     if (word === '&') {
@@ -337,38 +360,12 @@ function sectionTitle(name) {
 
     // Handle words with slashes (e.g., "enabled/disabled")
     if (word.includes('/')) {
-      const parts = word.split('/')
-      return parts.map((part, partIndex) => {
-        if (acronyms.has(part)) {
-          return part.toUpperCase()
-        }
-        if (index === 0 && partIndex === 0) {
-          return part.charAt(0).toUpperCase() + part.slice(1)
-        }
-        if (properNouns.has(part)) {
-          return part.charAt(0).toUpperCase() + part.slice(1)
-        }
-        return part
-      }).join('/')
-    }
-
-    // Acronyms: ALL CAPS
-    if (acronyms.has(word)) {
-      return word.toUpperCase()
-    }
-
-    // First word: always capitalize
-    if (index === 0) {
-      return word.charAt(0).toUpperCase() + word.slice(1)
-    }
-
-    // Proper nouns: capitalize
-    if (properNouns.has(word)) {
-      return word.charAt(0).toUpperCase() + word.slice(1)
+      return word.split('/')
+        .map((part, partIndex) => formatPart(part, index === 0 && partIndex === 0, index))
+        .join('/')
     }
 
-    // All other words in title: capitalize (standard title case)
-    return word.charAt(0).toUpperCase() + word.slice(1)
+    return formatPart(word, index === 0, index)
   }).join(' ')
 }