From 795f289cf30814cd1483e2cf75f5267329710bcb Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 7 Apr 2026 10:30:17 +0100 Subject: [PATCH 01/11] feat: add release-notes-writer skill for OpenShift telco features Adds a new skill that generates user-centric release notes from GitHub PR content. Uses git-pr-reader to extract diffs, then applies a structured four-part template (heading, what/how, why/result, call to action) with telco-specific tone and style guidelines. Co-Authored-By: Claude Opus 4.6 --- .../skills/release-notes-writer/SKILL.md | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 plugins/docs-tools/skills/release-notes-writer/SKILL.md diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md new file mode 100644 index 00000000..2c4cd85e --- /dev/null +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -0,0 +1,144 @@ +--- +name: release-notes-writer +description: Generate user-centric release notes for OpenShift telco features from GitHub PR content. Reads PR diffs, applies structured templates, and outputs AsciiDoc release note entries. +author: Kevin Quinn (kquinn@redhat.com) +allowed-tools: Read, Bash, Grep, Glob, Agent, WebFetch +--- + +# Release Notes Writer + +Write release notes for OpenShift telco features by analyzing GitHub PR content and applying a structured, user-centric template. + +## Capabilities + +- Read a GitHub PR to extract the technical context (files changed, descriptions, AsciiDoc content) +- Generate release note entries following the Red Hat OpenShift release note template +- Apply telco-specific tone and style guidelines +- Output AsciiDoc-formatted release note entries ready for inclusion in release note assemblies + +## Usage + +### From a GitHub PR + +When the user provides a PR URL, extract the content first: + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py read --url "" --filter "*.adoc" +``` + +Then apply the template and guidelines below to draft a release note. + +### From manual input + +The user can also provide a plain-text description of the feature. Apply the same template and guidelines to produce the release note. + +## Release note template + +Every release note entry MUST follow this four-part structure: + +### 1. Heading + +A short, descriptive summary of the feature or enhancement. Write it as a noun phrase, not a sentence. + +- Good: "CPU isolation for exec processes in low-latency pods" +- Bad: "This release adds a new feature that isolates CPUs" + +### 2. What and How (the feature) + +Describe the feature from the user's perspective. Focus on what the user can now do. Use second person ("you"). + +- Start with: "With this release, you can..." or "You can now..." +- Describe the user action, not the internal implementation +- Example: "You can use this feature to directly create and manage SR-IOV networks within your application namespaces." + +### 3. Why and Result (the benefit) + +Explain why the feature was added and how it benefits the user's workflow. One to two sentences. + +- Focus on the outcome for the user, not the engineering motivation +- Example: "Namespaced SR-IOV networks provide greater control over your network configurations and help to simplify your workflow." + +### 4. Call to action (documentation link) + +Provide a link to the detailed product documentation. + +- Format: `For more information, see link:[].` +- If the exact URL is not known, use a placeholder: `For more information, see xref:[
].` + +## Output format + +Produce the release note as an AsciiDoc snippet: + +```asciidoc +== + + + + + +For more information, see xref:[
]. +``` + +If multiple distinct features are covered in a single PR, produce one entry per feature. + +## Style guidelines + +Follow these rules strictly when writing release notes: + +### Tone + +- **Direct and concise.** Every word must earn its place. Remove filler, hedging, and thesis-style explanations. +- **Encouraging and positive.** Highlight value and new possibilities. Do not be dry or clinical. +- **Transparent.** Be honest about changes, even potentially negative ones, to maintain trust. +- **User-centric.** Write from the user's perspective, using the language they know. + +### Do + +- Use second person ("you can", "your cluster") +- Use active voice +- Use present tense for the feature description +- State clearly when a Technology Preview feature moves to fully supported +- Keep each release note entry to 3-5 sentences total (excluding the heading and link) + +### Do not + +- Use "discontinued" -- instead say "We are taking our product in the following direction..." +- Use corporate-speak: "cost-effective," "reducing operational expenses," "enhances efficiency," "streamlines operations" +- Over-explain the technical internals unless the user needs them to act +- Use jargon without context -- if a term must be used, add a brief parenthetical explanation +- Write more than two paragraphs per entry (excluding the link) + +## Workflow + +1. **Extract context.** Read the PR diff and description to identify the core functionality and the problem it solves. +2. **Identify the audience.** Determine which telco persona benefits (RAN engineer, platform admin, network operator, etc.). +3. **Draft the heading.** Write a concise noun-phrase summary. +4. **Write the What/How.** One to two sentences from the user's perspective. +5. **Write the Why/Result.** One to two sentences on the benefit. +6. **Add the link.** Include an xref or URL placeholder. +7. **Polish.** Check against the style guidelines. Cut any word that does not add meaning. + +## Example + +Given a PR that adds ExecCPUAffinity documentation for low-latency workloads, the output should look like: + +```asciidoc +== CPU isolation for exec processes in low-latency pods + +With this release, you can protect latency-sensitive workloads from performance +degradation caused by `oc exec` and shell processes. When you apply a +`PerformanceProfile`, exec processes are automatically pinned to a designated CPU +so they do not interrupt your workload CPUs. + +This feature is enabled by default for guaranteed QoS pods with whole-integer CPU +requests. You can disable it per-pod with an annotation if your workloads require +the previous behavior. + +For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-low-latency-perf-profile[Protecting low-latency workloads from exec process interruption]. +``` + +## Integration with other skills + +- **git-pr-reader**: Use to extract PR metadata, file diffs, and AsciiDoc content before drafting +- **docs-review-style**: Use after drafting to verify style guide compliance +- **rh-ssg-release-notes**: Use after drafting to verify SSG release note conventions From 091262d7e45ec61d8e555c76d9da634da836c655 Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 7 Apr 2026 10:42:59 +0100 Subject: [PATCH 02/11] fix: replace jargon in release note example with clearer wording Change "deterministic performance" to "consistent, predictable performance" in the ExecCPUAffinity example release note. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/skills/release-notes-writer/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 2c4cd85e..77c446dd 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -130,9 +130,10 @@ degradation caused by `oc exec` and shell processes. When you apply a `PerformanceProfile`, exec processes are automatically pinned to a designated CPU so they do not interrupt your workload CPUs. -This feature is enabled by default for guaranteed QoS pods with whole-integer CPU -requests. You can disable it per-pod with an annotation if your workloads require -the previous behavior. +This feature is enabled by default for Guaranteed QoS pods with whole-integer CPU +requests, so your Telco RAN DU and 5G Core applications maintain consistent, +predictable performance without additional configuration. You can disable it +per-pod with an annotation if your workloads require the previous behavior. For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-low-latency-perf-profile[Protecting low-latency workloads from exec process interruption]. ``` From feb7927122be5da9743ce12cf092f1bf64227f18 Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 7 Apr 2026 11:18:02 +0100 Subject: [PATCH 03/11] feat: align release notes skill with OCP repo format Update templates to use bullet entries with JIRA tracking comments instead of section headings. Add four template types: new feature, bug fix (Before/Consequence/Fix narrative), deprecated feature, and Technology Preview to GA. Include real examples from OCP release notes. Co-Authored-By: Claude Opus 4.6 --- .../skills/release-notes-writer/SKILL.md | 100 ++++++++++-------- 1 file changed, 55 insertions(+), 45 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 77c446dd..197d18a5 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -32,54 +32,62 @@ Then apply the template and guidelines below to draft a release note. The user can also provide a plain-text description of the feature. Apply the same template and guidelines to produce the release note. -## Release note template +## Release note templates -Every release note entry MUST follow this four-part structure: +Release notes in the OCP repo are AsciiDoc bullet entries (`*`) under category sections. Each entry includes a JIRA tracking ID. There are two templates depending on the type of change. -### 1. Heading +### New feature or enhancement -A short, descriptive summary of the feature or enhancement. Write it as a noun phrase, not a sentence. +A single bullet entry with a JIRA comment above it. Structure: -- Good: "CPU isolation for exec processes in low-latency pods" -- Bad: "This release adds a new feature that isolates CPUs" +1. **JIRA tracking comment** — AsciiDoc comment with the JIRA ID +2. **What you can now do** — Start with "With this release, you can..." or "You can now..." +3. **Why it matters** — One sentence on the benefit to the user +4. **Documentation link** — "For more information, see xref:..." -### 2. What and How (the feature) +Format: -Describe the feature from the user's perspective. Focus on what the user can now do. Use second person ("you"). - -- Start with: "With this release, you can..." or "You can now..." -- Describe the user action, not the internal implementation -- Example: "You can use this feature to directly create and manage SR-IOV networks within your application namespaces." +```asciidoc +// +* With this release, you can . . ++ +For more information, see xref:[
]. +``` -### 3. Why and Result (the benefit) +If multiple distinct features are covered in a single PR, produce one entry per feature. -Explain why the feature was added and how it benefits the user's workflow. One to two sentences. +### Bug fix (fixed issue) -- Focus on the outcome for the user, not the engineering motivation -- Example: "Namespaced SR-IOV networks provide greater control over your network configurations and help to simplify your workflow." +A single narrative paragraph using the **Before / Consequence / Fix** flow, with the JIRA ID in parentheses at the end. Do not use subheadings — write it as plain prose. -### 4. Call to action (documentation link) +Format: -Provide a link to the detailed product documentation. +```asciidoc +// +* Before this update, . As a consequence, . With this release, . () +``` -- Format: `For more information, see link:[].` -- If the exact URL is not known, use a placeholder: `For more information, see xref:[
].` +### Deprecated feature -## Output format +Use when a feature or parameter is being removed or replaced. Do not say "discontinued." Frame the change positively. -Produce the release note as an AsciiDoc snippet: +Format: ```asciidoc -== +// +* In this release, . . () +``` - +### Technology Preview to GA - +Use when a Technology Preview feature moves to fully supported (General Availability). -For more information, see xref:[
]. -``` +Format: -If multiple distinct features are covered in a single PR, produce one entry per feature. +```asciidoc +// +* The feature is now fully supported. Previously available as a Technology Preview, this feature . For more information, see xref:[
]. +``` ## Style guidelines @@ -111,31 +119,33 @@ Follow these rules strictly when writing release notes: ## Workflow 1. **Extract context.** Read the PR diff and description to identify the core functionality and the problem it solves. -2. **Identify the audience.** Determine which telco persona benefits (RAN engineer, platform admin, network operator, etc.). -3. **Draft the heading.** Write a concise noun-phrase summary. -4. **Write the What/How.** One to two sentences from the user's perspective. -5. **Write the Why/Result.** One to two sentences on the benefit. -6. **Add the link.** Include an xref or URL placeholder. +2. **Identify the type.** Determine whether this is a new feature, bug fix, deprecation, or TP-to-GA change. +3. **Extract the JIRA ID.** Pull the JIRA tracking ID from the PR title, description, or branch name. +4. **Apply the template.** Use the matching template for the change type. +5. **Write from the user's perspective.** Use second person, active voice, present tense. +6. **Add the link.** Include an xref or URL placeholder for new features and TP-to-GA entries. 7. **Polish.** Check against the style guidelines. Cut any word that does not add meaning. -## Example +## Examples + +### New feature example -Given a PR that adds ExecCPUAffinity documentation for low-latency workloads, the output should look like: +Given a PR that adds ExecCPUAffinity documentation for low-latency workloads (TELCODOCS-2496): ```asciidoc -== CPU isolation for exec processes in low-latency pods +// TELCODOCS-2496 +* With this release, you can protect latency-sensitive workloads from performance degradation caused by `oc exec` and shell processes. When you apply a `PerformanceProfile`, exec processes are automatically pinned to a designated CPU so they do not interrupt your workload CPUs. This feature is enabled by default for Guaranteed QoS pods with whole-integer CPU requests, so your Telco RAN DU and 5G Core applications maintain consistent, predictable performance without additional configuration. ++ +For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-low-latency-perf-profile[Protecting low-latency workloads from exec process interruption]. +``` -With this release, you can protect latency-sensitive workloads from performance -degradation caused by `oc exec` and shell processes. When you apply a -`PerformanceProfile`, exec processes are automatically pinned to a designated CPU -so they do not interrupt your workload CPUs. +### Bug fix example -This feature is enabled by default for Guaranteed QoS pods with whole-integer CPU -requests, so your Telco RAN DU and 5G Core applications maintain consistent, -predictable performance without additional configuration. You can disable it -per-pod with an annotation if your workloads require the previous behavior. +Given a PR that fixes a vSphere validation issue (OCPBUGS-63584): -For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-low-latency-perf-profile[Protecting low-latency workloads from exec process interruption]. +```asciidoc +// OCPBUGS-63584 +* Before this update, the vSphere platform configuration lacked a validation check to prevent the simultaneous definition of both a custom virtual machine template and a `clusterOSImage` parameter. As a consequence, users could provide both parameters in the installation configuration, leading to ambiguity and potential deployment failures. With this release, the vSphere validation logic has been updated to ensure that `template` and `clusterOSImage` parameters are treated as mutually exclusive, returning a specific error message if both fields are populated. (OCPBUGS-63584) ``` ## Integration with other skills From 9538874577906be8bfbaf894236abc6300440c0d Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Wed, 8 Apr 2026 09:55:35 +0100 Subject: [PATCH 04/11] fix: add "As a result" closing to bug fix template Update the bug fix template to use a four-beat flow (Before/Consequence/Fix/Result) matching the OCP release note convention. Update the example to match. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/skills/release-notes-writer/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 197d18a5..30263708 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -58,13 +58,13 @@ If multiple distinct features are covered in a single PR, produce one entry per ### Bug fix (fixed issue) -A single narrative paragraph using the **Before / Consequence / Fix** flow, with the JIRA ID in parentheses at the end. Do not use subheadings — write it as plain prose. +A single narrative paragraph using the **Before / Consequence / Fix / Result** flow, with the JIRA ID in parentheses at the end. Do not use subheadings — write it as plain prose. Format: ```asciidoc // -* Before this update, . As a consequence, . With this release, . () +* Before this update, . . With this release, . As a result, . () ``` ### Deprecated feature @@ -145,7 +145,7 @@ Given a PR that fixes a vSphere validation issue (OCPBUGS-63584): ```asciidoc // OCPBUGS-63584 -* Before this update, the vSphere platform configuration lacked a validation check to prevent the simultaneous definition of both a custom virtual machine template and a `clusterOSImage` parameter. As a consequence, users could provide both parameters in the installation configuration, leading to ambiguity and potential deployment failures. With this release, the vSphere validation logic has been updated to ensure that `template` and `clusterOSImage` parameters are treated as mutually exclusive, returning a specific error message if both fields are populated. (OCPBUGS-63584) +* Before this update, the vSphere platform configuration lacked a validation check to prevent the simultaneous definition of both a custom virtual machine template and a `clusterOSImage` parameter. This issue allowed users to provide both parameters in the installation configuration, leading to ambiguity and potential deployment failures. With this release, the vSphere validation logic has been updated to ensure that `template` and `clusterOSImage` parameters are treated as mutually exclusive. As a result, a specific error message is returned if both fields are populated, which prevents misconfiguration. (OCPBUGS-63584) ``` ## Integration with other skills From 6e9ed7cc05d13927e479b622849a674d88426d49 Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Wed, 22 Apr 2026 11:25:42 +0100 Subject: [PATCH 05/11] updating skill based on check 3 --- .../skills/release-notes-writer/SKILL.md | 64 ++++--------------- .../skills/rh-ssg-release-notes/SKILL.md | 4 +- 2 files changed, 15 insertions(+), 53 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 30263708..1443503b 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -1,37 +1,19 @@ --- name: release-notes-writer description: Generate user-centric release notes for OpenShift telco features from GitHub PR content. Reads PR diffs, applies structured templates, and outputs AsciiDoc release note entries. -author: Kevin Quinn (kquinn@redhat.com) allowed-tools: Read, Bash, Grep, Glob, Agent, WebFetch --- # Release Notes Writer -Write release notes for OpenShift telco features by analyzing GitHub PR content and applying a structured, user-centric template. +Write release notes for OpenShift telco features by analyzing GitHub PR content or user-provided descriptions, applying structured templates below. -## Capabilities - -- Read a GitHub PR to extract the technical context (files changed, descriptions, AsciiDoc content) -- Generate release note entries following the Red Hat OpenShift release note template -- Apply telco-specific tone and style guidelines -- Output AsciiDoc-formatted release note entries ready for inclusion in release note assemblies - -## Usage - -### From a GitHub PR - -When the user provides a PR URL, extract the content first: +When given a PR URL, extract content first: ```bash python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py read --url "" --filter "*.adoc" ``` -Then apply the template and guidelines below to draft a release note. - -### From manual input - -The user can also provide a plain-text description of the feature. Apply the same template and guidelines to produce the release note. - ## Release note templates Release notes in the OCP repo are AsciiDoc bullet entries (`*`) under category sections. Each entry includes a JIRA tracking ID. There are two templates depending on the type of change. @@ -91,40 +73,20 @@ Format: ## Style guidelines -Follow these rules strictly when writing release notes: - -### Tone - -- **Direct and concise.** Every word must earn its place. Remove filler, hedging, and thesis-style explanations. -- **Encouraging and positive.** Highlight value and new possibilities. Do not be dry or clinical. -- **Transparent.** Be honest about changes, even potentially negative ones, to maintain trust. -- **User-centric.** Write from the user's perspective, using the language they know. - -### Do - -- Use second person ("you can", "your cluster") -- Use active voice -- Use present tense for the feature description -- State clearly when a Technology Preview feature moves to fully supported -- Keep each release note entry to 3-5 sentences total (excluding the heading and link) - -### Do not - -- Use "discontinued" -- instead say "We are taking our product in the following direction..." -- Use corporate-speak: "cost-effective," "reducing operational expenses," "enhances efficiency," "streamlines operations" -- Over-explain the technical internals unless the user needs them to act -- Use jargon without context -- if a term must be used, add a brief parenthetical explanation -- Write more than two paragraphs per entry (excluding the link) +- Second person ("you can", "your cluster"), active voice, present tense +- Direct and concise — every word must earn its place. No filler, hedging, or corporate-speak ("cost-effective," "streamlines operations") +- 3-5 sentences per entry, max two paragraphs (excluding link) +- Never use "discontinued" — instead frame as "We are taking our product in the following direction..." +- No unexplained jargon — add a brief parenthetical if a term must be used +- Do not over-explain technical internals unless the user needs them to act ## Workflow -1. **Extract context.** Read the PR diff and description to identify the core functionality and the problem it solves. -2. **Identify the type.** Determine whether this is a new feature, bug fix, deprecation, or TP-to-GA change. -3. **Extract the JIRA ID.** Pull the JIRA tracking ID from the PR title, description, or branch name. -4. **Apply the template.** Use the matching template for the change type. -5. **Write from the user's perspective.** Use second person, active voice, present tense. -6. **Add the link.** Include an xref or URL placeholder for new features and TP-to-GA entries. -7. **Polish.** Check against the style guidelines. Cut any word that does not add meaning. +1. **Extract context** — read PR diff/description, identify core functionality and the problem it solves +2. **Classify** — new feature, bug fix, deprecation, or TP-to-GA +3. **Extract JIRA ID** — from PR title, description, or branch name +4. **Draft** — apply the matching template, include xref link for features and TP-to-GA entries +5. **Review** — verify against style guidelines, cut any word that does not add meaning ## Examples diff --git a/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md b/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md index 8e29fd72..c511e2f6 100644 --- a/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md +++ b/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md @@ -1,7 +1,7 @@ --- -context: fork name: rh-ssg-release-notes -description: Review Red Hat release notes for SSG compliance — tense rules (present default, past for "before this update"), informative headings (sentence case, no gerunds, under 120 chars), Jira references on known/fixed issues, AsciiDoc formatting (description lists, + attachment), and release note types: new features, enhancements, rebases (X.Y.Z format), Technology Preview entries, deprecated features, removed features, known issues (Cause > Consequence > Workaround > Result), and fixed issues (CCFR pattern). Use this skill whenever reviewing, writing, or checking release notes for any Red Hat product. +description: "Review Red Hat release notes for SSG compliance — tense rules (present default, past for \"before this update\"), informative headings (sentence case, no gerunds, under 120 chars), Jira references on known/fixed issues, AsciiDoc formatting (description lists, + attachment), and release note types: new features, enhancements, rebases (X.Y.Z format), Technology Preview entries, deprecated features, removed features, known issues (Cause > Consequence > Workaround > Result), and fixed issues (CCFR pattern). Use this skill whenever reviewing, writing, or checking release notes for any Red Hat product." +allowed-tools: Read, Glob, Grep, Edit, Bash --- # Red Hat SSG: Release Notes review skill From e3a676d6fe66b26a9944e4c789510c5385832e0e Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Thu, 23 Apr 2026 12:44:53 +0100 Subject: [PATCH 06/11] feat: use titled sections for new feature release notes New features now use section ID + heading with prose paragraphs instead of bullet point entries, matching the OCP repo format. Co-Authored-By: Claude Opus 4.6 --- .../skills/release-notes-writer/SKILL.md | 31 +++++++++++++------ 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 1443503b..87e8a5a5 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -20,23 +20,29 @@ Release notes in the OCP repo are AsciiDoc bullet entries (`*`) under category s ### New feature or enhancement -A single bullet entry with a JIRA comment above it. Structure: +A titled section with prose paragraphs (no bullet points). Structure: 1. **JIRA tracking comment** — AsciiDoc comment with the JIRA ID -2. **What you can now do** — Start with "With this release, you can..." or "You can now..." -3. **Why it matters** — One sentence on the benefit to the user -4. **Documentation link** — "For more information, see xref:..." +2. **Section ID and title** — An `[id=...]` anchor and `==` heading that describes the feature concisely +3. **What you can now do** — Start with "With this release, you can..." or "You can now..." +4. **Why it matters** — One sentence on the benefit to the user +5. **Documentation link** — "For more information, see xref:..." Format: ```asciidoc // -* With this release, you can . . -+ +[id="ocp-release-notes-_{context}"] +== + +With this release, you can . . + + + For more information, see xref:[
]. ``` -If multiple distinct features are covered in a single PR, produce one entry per feature. +If multiple distinct features are covered in a single PR, produce one entry per feature, each with its own section ID and heading. ### Bug fix (fixed issue) @@ -96,9 +102,14 @@ Given a PR that adds ExecCPUAffinity documentation for low-latency workloads (TE ```asciidoc // TELCODOCS-2496 -* With this release, you can protect latency-sensitive workloads from performance degradation caused by `oc exec` and shell processes. When you apply a `PerformanceProfile`, exec processes are automatically pinned to a designated CPU so they do not interrupt your workload CPUs. This feature is enabled by default for Guaranteed QoS pods with whole-integer CPU requests, so your Telco RAN DU and 5G Core applications maintain consistent, predictable performance without additional configuration. -+ -For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-low-latency-perf-profile[Protecting low-latency workloads from exec process interruption]. +[id="ocp-release-notes-exec-cpu-affinity_{context}"] +== CRI-O ExecCPUAffinity protects low-latency workloads from exec process interruption + +With this release, you can protect latency-sensitive workloads from performance degradation caused by `oc exec` and shell processes. When you apply a `PerformanceProfile`, the CRI-O `ExecCPUAffinity` feature automatically pins exec processes to a designated CPU within the container's allocated set, preventing them from running on your workload CPUs. + +This feature is enabled by default for `Guaranteed` QoS pods with whole-integer CPU requests and requires no additional configuration. You can disable it per profile by adding the `performance.openshift.io/exec-cpu-affinity: "disable"` annotation to the `PerformanceProfile`. + +For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-tuning-low-latency-nodes-with-perf-profile[How ExecCPUAffinity prevents latency spikes from exec operations]. ``` ### Bug fix example From 7ce1abbb67f90f93f91baa2e3067b1177a91702e Mon Sep 17 00:00:00 2001 From: Kevin Quinn Date: Tue, 28 Apr 2026 10:09:01 +0100 Subject: [PATCH 07/11] Updating skill --- .../skills/release-notes-writer/SKILL.md | 300 ++++++++++++++++-- 1 file changed, 274 insertions(+), 26 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 87e8a5a5..2d2aced5 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -16,45 +16,96 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/git-pr-reader/scripts/git_pr_reader.py read ## Release note templates -Release notes in the OCP repo are AsciiDoc bullet entries (`*`) under category sections. Each entry includes a JIRA tracking ID. There are two templates depending on the type of change. +Release notes in the OCP repo are organized under category sections (e.g., `== Networking`, `== Installation and update`). Each entry uses AsciiDoc **definition list** format with `+` continuation blocks. Each entry includes a JIRA tracking ID as a comment above it. There are several templates depending on the type of change. ### New feature or enhancement -A titled section with prose paragraphs (no bullet points). Structure: +A definition list entry with prose continuation paragraphs. Structure: 1. **JIRA tracking comment** — AsciiDoc comment with the JIRA ID -2. **Section ID and title** — An `[id=...]` anchor and `==` heading that describes the feature concisely -3. **What you can now do** — Start with "With this release, you can..." or "You can now..." +2. **Definition list title** — A concise title ending with `::` +3. **What you can now do** — Start with "With this release, you can...", "You can now...", or "As of this update, you can..." 4. **Why it matters** — One sentence on the benefit to the user -5. **Documentation link** — "For more information, see xref:..." +5. **Documentation link** — "For more information, see xref:../..." Format: ```asciidoc // -[id="ocp-release-notes-_{context}"] -== +:: ++ +. . ++ + ++ +For more information, see xref:../.adoc#[
]. +``` -With this release, you can . . +**xref format**: All xrefs in release notes modules must start with `../` because the module lives in `modules/` and references assemblies at the repo root. Always use `xref:../path/to/assembly.adoc#anchor[Link text]`. - +**Bullet lists inside an entry**: When an entry contains a list, wrap the `*` items in `--` open block delimiters so they nest correctly inside the definition list continuation: + +```asciidoc +:: ++ +<Intro text>: ++ +-- +* Item one +* Item two +-- ++ +For more information, see xref:../<path>.adoc#<anchor>[<title>]. +``` -For more information, see xref:<assembly-or-module-id>[<section title>]. +**Admonition blocks inside an entry**: You can include `[NOTE]`, `[IMPORTANT]`, or `[WARNING]` blocks inside a continuation. Place them after a `+` continuation marker: + +```asciidoc +<Title>:: ++ +<Main text>. ++ +[NOTE] +==== +<Note content>. +==== ``` -If multiple distinct features are covered in a single PR, produce one entry per feature, each with its own section ID and heading. +If multiple distinct features are covered in a single PR, produce one entry per feature, each as its own definition list item. ### Bug fix (fixed issue) -A single narrative paragraph using the **Before / Consequence / Fix / Result** flow, with the JIRA ID in parentheses at the end. Do not use subheadings — write it as plain prose. +A single bullet (`*`) paragraph using the **Before / Consequence / Fix / Result** flow, with a JIRA link at the end. Fixed issues are grouped under category subsections (e.g., `== Installer`, `== Networking`) with `[id=...]` anchors. Do not use definition list format for bug fixes. Format: ```asciidoc -// <JIRA-ID> -* Before this update, <description of the previous behavior or problem when the user did something specific>. <Consequence — the impact on the user>. With this release, <what was changed or fixed>. As a result, <positive outcome for the user>. (<JIRA-ID>) +[id="rn-ocp-release-note-<category>-fixed-issues_{context}"] +== <Category name> + +* Before this update, <description of the previous behavior or problem>. As a consequence, <impact on the user>. With this release, <what was changed or fixed>. As a result, <positive outcome for the user>. (link:https://issues.redhat.com/browse/<JIRA-ID>[<JIRA-ID>]) +``` + +**JIRA link format**: Always use `link:https://issues.redhat.com/browse/JIRA-ID[JIRA-ID]` — not just the ID in parentheses. This creates a clickable link in the rendered docs. + +### Known issue + +A bullet (`*`) paragraph describing an ongoing problem the user may encounter, with a workaround if available. Known issues are listed as flat bullets under the main `= Known issues` heading — they are **not** grouped under category subsections like fixed issues. Use "Currently" to open the entry. + +Format (with workaround): + +```asciidoc +* Currently, <description of the problem and when it occurs>. As a consequence, <impact on the user>. As a workaround, <mitigation steps>. (link:https://issues.redhat.com/browse/<JIRA-ID>[<JIRA-ID>]) +``` + +Format (no workaround available): + +```asciidoc +* Currently, <description of the problem and when it occurs>. As a consequence, <impact on the user>. (link:https://issues.redhat.com/browse/<JIRA-ID>[<JIRA-ID>]) ``` +**Multi-paragraph known issues**: For complex workarounds with code blocks or steps, use `+` continuation after the opening bullet, same as definition list continuations. Wrap bullet lists in `--` open block delimiters. + ### Deprecated feature Use when a feature or parameter is being removed or replaced. Do not say "discontinued." Frame the change positively. @@ -74,9 +125,59 @@ Format: ```asciidoc // <JIRA-ID> -* The <feature name> feature is now fully supported. Previously available as a Technology Preview, this feature <brief description of what it does>. For more information, see xref:<assembly-or-module-id>[<section title>]. +<Feature name> (Generally Available):: ++ +<Brief description of what the feature does>. ++ +This feature was introduced in {product-title} <version> with Technology Preview status. This feature is now supported as generally available in {product-title} {product-version}. ++ +For more information, see xref:../<path-to-assembly>.adoc#<anchor>[<section title>]. ``` +### Z-stream (maintenance release) + +Z-stream release notes are separate modules (`zstream-4-YY-N.adoc`) included from the main release notes assembly. They have a fixed structure with boilerplate sections. Entries use the same **Before / Consequence / Fix / Result** bullet format as GA fixed issues — no category subsections. + +File structure: + +```asciidoc +// Module included in the following assemblies: +// +// * release_notes/ocp-4-YY-release-notes.adoc + +:_mod-docs-content-type: REFERENCE +[id="zstream-4-YY-N_{context}"] += <RHBA|RHSA>-YYYY:NNNN - {product-title} {product-version}.N fixed issues advisory + +Issued: DD Month YYYY + +[role="_abstract"] +{product-title} release {product-version}.N is now available. The list of fixed issues that are included in the update is documented in the link:https://access.redhat.com/errata/<RHBA|RHSA>-YYYY:NNNN[<RHBA|RHSA>-YYYY:NNNN] advisory. The RPM packages that are included in the update are provided by the link:https://access.redhat.com/errata/RHBA-YYYY:NNNN[RHBA-YYYY:NNNN] advisory. + +Space precluded documenting all of the container images for this release in the advisory. + +You can view the container images in this release by running the following command: + +[source,terminal] +---- +$ oc adm release info 4.YY.N --pullspecs +---- + +[id="zstream-4-YY-N-fixed-issues_{context}"] +== Fixed issues + +* Before this update, <problem>. As a consequence, <impact>. With this release, <fix>. As a result, <outcome>. (link:https://issues.redhat.com/browse/<JIRA-ID>[<JIRA-ID>]) + +[id="zstream-4-YY-N-updating_{context}"] +== Updating + +To update an {product-title} 4.YY cluster to this latest release, see xref:../updating/updating_a_cluster/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster using the CLI]. +``` + +**Z-stream enhancements**: Some z-stream releases include an optional `== Enhancements` section before `== Fixed issues`. Enhancement entries use `+` continuation blocks (same format as definition list entries but without the `::` — just a plain `*` bullet with continuation paragraphs). + +**JIRA link domains**: Z-stream entries may use either `issues.redhat.com/browse/` or `redhat.atlassian.net/browse/` for JIRA links — both are valid. Use whichever domain the JIRA ticket originates from. + ## Style guidelines - Second person ("you can", "your cluster"), active voice, present tense @@ -96,29 +197,176 @@ Format: ## Examples -### New feature example +### New feature — simple (single paragraph with xref) -Given a PR that adds ExecCPUAffinity documentation for low-latency workloads (TELCODOCS-2496): +```asciidoc +// TELCODOCS-2565 +Multi-network policy backend uses nftables:: ++ +With this release, the multi-network policy backend uses `nftables` instead of `iptables`. The `iptables` backend has been removed and there is no option to revert to it. The `MultiNetworkPolicy` API and user-facing configuration are unchanged, so your existing multi-network policies continue to work without modification. ++ +The Cluster Network Operator (CNO) now automatically creates and manages the `multi-networkpolicy-custom-rules` ConfigMap for IPv6 NDP support. You no longer need to create this resource manually. ++ +For more information, see xref:../networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc#configuring-multi-network-policy[Configuring multi-network policy]. +``` + +### New feature — with configuration detail ```asciidoc // TELCODOCS-2496 -[id="ocp-release-notes-exec-cpu-affinity_{context}"] -== CRI-O ExecCPUAffinity protects low-latency workloads from exec process interruption - +CRI-O ExecCPUAffinity protects low-latency workloads from exec process interruption:: ++ With this release, you can protect latency-sensitive workloads from performance degradation caused by `oc exec` and shell processes. When you apply a `PerformanceProfile`, the CRI-O `ExecCPUAffinity` feature automatically pins exec processes to a designated CPU within the container's allocated set, preventing them from running on your workload CPUs. - ++ This feature is enabled by default for `Guaranteed` QoS pods with whole-integer CPU requests and requires no additional configuration. You can disable it per profile by adding the `performance.openshift.io/exec-cpu-affinity: "disable"` annotation to the `PerformanceProfile`. ++ +For more information, see xref:../scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-tuning-low-latency-nodes-with-perf-profile[How ExecCPUAffinity prevents latency spikes from exec operations]. +``` + +### New feature — brief (no second paragraph) -For more information, see xref:scalability_and_performance/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-protecting-low-latency-workloads_cnf-tuning-low-latency-nodes-with-perf-profile[How ExecCPUAffinity prevents latency spikes from exec operations]. +```asciidoc +// OSDOCS-12345 +Installing a cluster on {azure-full} uses Marketplace images by default:: ++ +As of this update, the {product-title} installation program uses Marketplace images by default when installing a cluster on {azure-short}. This speeds up the installation by removing the need to upload a virtual hard disk to {azure-short} and create an image during installation. This feature is not supported on Azure Stack Hub, or for {azure-short} installations that use Confidential VMs. +``` + +### New feature — Technology Preview + +```asciidoc +// OSDOCS-12346 +Installing a cluster on {aws-short} with a user-provisioned DNS (Technology Preview):: ++ +You can enable a user-provisioned domain name server (DNS) instead of the default cluster-provisioned DNS solution. For example, your organization's security policies might not allow the use of public DNS services such as {aws-first} DNS. If you use this feature, you must provide your own DNS solution that includes records for `api.<cluster_name>.<base_domain>.` and `*.apps.<cluster_name>.<base_domain>.`. Enabling a user-provisioned DNS is available as a Technology Preview feature. ++ +For more information, see xref:../installing/installing_aws/ipi/installing-aws-customizations.adoc#installation-aws-enabling-user-managed-DNS_installing-aws-customizations[Enabling a user-managed DNS] and xref:../installing/installing_aws/ipi/installing-aws-customizations.adoc#installation-aws-provisioning-own-dns-records_installing-aws-customizations[Provisioning your own DNS records]. +``` + +### New feature — with bullet list + +```asciidoc +MetalLB Operator status reporting:: ++ +You can now use enhanced MetalLB Operator reporting features to view real-time operational data for IP address allocation and Border Gateway Protocol (BGP) connectivity. Previously, viewing this information required manual log inspection across multiple controllers. With this release, you can monitor your network health and resolve connectivity issues directly through the following custom resources: ++ +-- +* `IPAddressPool`: Monitor cluster-wide IP address allocation through the `status` field to track usage and prevent address exhaustion. +* `ServiceBGPStatus`: Verify which service IP addresses are announced to specific BGP peers to ensure correct route advertisements. +* `BGPSessionStatus`: Check the real-time state of BGP and Bidirectional Forwarding Detection sessions to quickly identify connectivity drops. +-- ++ +For more information, see xref:../networking/ingress_load_balancing/metallb/monitoring-metallb-status.adoc[Monitoring MetalLB configuration status]. +``` + +### New feature — with admonition block + +```asciidoc +Support for {vmw-full} Foundation 9 and VMware Cloud Foundation 9:: ++ +You can now install {product-title} on {vmw-full} Foundation (VVF) 9 and VMware Cloud Foundation (VCF) 9. ++ +[NOTE] +==== +The following additional VCF and VVF components are outside the scope of Red Hat support: + +* Management: VCF Operations, VCF Automation, VCF Fleet Management, and VCF Identity Broker. +* Networking: VMware NSX Container Plugin (NCP). +* Migration: VMware HCX. +==== +``` + +### Technology Preview to GA example + +```asciidoc +Running firmware upgrades for hosts in deployed bare metal clusters (Generally Available):: ++ +For hosts in deployed bare metal clusters, you can update firmware attributes and the firmware image. As a result, you can run firmware upgrades and update BIOS settings for hosts that are already provisioned without fully deprovisioning them. Performing a live update to the `HostFirmwareComponents`, `HostFirmareSettings`, or `HostUpdatePolicy` resource can be a destructive and destabilizing action. Perform these updates only after careful consideration. ++ +This feature was introduced in {product-title} 4.18 with Technology Preview status. This feature is now supported as generally available in {product-title} {product-version}. ++ +For more information, see xref:../installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc#bmo-performing-a-live-update-to-the-hostfirmwaresettings-resource_bare-metal-postinstallation-configuration[Performing a live update to the HostFirmwareSettings resource], +xref:../installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc#bmo-performing-a-live-update-to-the-hostfirmwarecomponents-resource_bare-metal-postinstallation-configuration[Performing a live update to the HostFirmwareComponents resource], and +xref:../installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc#bmo-setting-the-hostupdatepolicy-resource_bare-metal-postinstallation-configuration[Setting the HostUpdatePolicy resource]. +``` + +### Known issue — simple with workaround + +```asciidoc +* Currently, on clusters with SR-IOV network virtual functions configured, a race condition might occur between system services responsible for network device renaming and the TuneD service managed by the Node Tuning Operator. As a consequence, the TuneD profile might become degraded after the node restarts, leading to performance degradation. As a workaround, restart the TuneD pod to restore the profile state. (link:https://issues.redhat.com/browse/OCPBUGS-41934[OCPBUGS-41934]) +``` + +### Known issue — multi-paragraph with code block + +```asciidoc +* If you mirrored the {product-title} release images to the registry of a disconnected environment by using the `oc adm release mirror` command, the release image Sigstore signature is not mirrored with the image. ++ +This has become an issue in {product-title} {product-version}, because the `openshift` cluster image policy is now deployed to the cluster by default. This policy causes CRI-O to automatically verify the Sigstore signature when pulling images into a cluster. (link:https://issues.redhat.com/browse/OCPBUGS-70297[OCPBUGS-70297]) ++ +If you cannot use the oc-mirror plugin v2, you can use the `oc image mirror` command to mirror the Sigstore signature into your mirror registry by using a command similar to the following: ++ +-- +[source,terminal] +---- +$ oc image mirror "quay.io/openshift-release-dev/ocp-release:${RELEASE_DIGEST}.sig" "${LOCAL_REGISTRY}/${LOCAL_RELEASE_IMAGES_REPOSITORY}:${RELEASE_DIGEST}.sig" +---- +-- +``` + +### Known issue — with recovery steps list + +```asciidoc +* While Day 2 firmware updates and BIOS attribute reconfiguration for bare-metal hosts are generally available with this release, the Bare Metal Operator (BMO) does not provide a native mechanism to cancel a firmware update request once initiated. If a firmware update or setting change for `HostFirmwareComponents` or `HostFirmwareSettings` resources fails, returns an error, or becomes indefinitely stuck, you can try to recover by using the following steps: ++ +-- +* Removing the changes to the `HostFirmwareComponents` and `HostFirmwareSettings` resources. +* Setting the node to `online: false` to trigger a reboot. +* If the issue persists, deleting the Ironic pod. +-- ++ +A native abort capability for servicing operations might be planned for a future release. ``` -### Bug fix example +### Bug fix examples + +Multiple bug fixes under a category subsection: + +```asciidoc +[id="rn-ocp-release-note-installer-fixed-issues_{context}"] +== Installer + +* Before this update, the vSphere platform configuration lacked a validation check to prevent the simultaneous definition of both a custom virtual machine template and a `clusterOSImage` parameter. As a consequence, users could provide both parameters in the installation configuration, leading to ambiguity and potential deployment failures. With this release, the vSphere validation logic has been updated to ensure that template and `clusterOSImage` parameters are treated as mutually exclusive, returning a specific error message if both fields are populated. (link:https://issues.redhat.com/browse/OCPBUGS-63584[OCPBUGS-63584]) + +* Before this update, a race condition occurred when multiple reconciliation loops or concurrent processes attempted to add a virtual machine (VM) to a vSphere Host Group simultaneously due to the provider lacking a check to see if the VM was already a member. Consequently, the vSphere API could return errors during the cluster reconfiguration task, leading to reconciliation failures and preventing the VM from being correctly associated with its designated zone or host group. With this release, the zonal logic has been updated to verify the VM's membership within the target host group before initiating a reconfiguration task, ensuring the operation is only performed if the VM is not already present. (link:https://issues.redhat.com/browse/OCPBUGS-60765[OCPBUGS-60765]) +``` -Given a PR that fixes a vSphere validation issue (OCPBUGS-63584): +Single bug fix under a category: ```asciidoc -// OCPBUGS-63584 -* Before this update, the vSphere platform configuration lacked a validation check to prevent the simultaneous definition of both a custom virtual machine template and a `clusterOSImage` parameter. This issue allowed users to provide both parameters in the installation configuration, leading to ambiguity and potential deployment failures. With this release, the vSphere validation logic has been updated to ensure that `template` and `clusterOSImage` parameters are treated as mutually exclusive. As a result, a specific error message is returned if both fields are populated, which prevents misconfiguration. (OCPBUGS-63584) +[id="rn-ocp-release-note-networking-fixed-issues_{context}"] +== Networking + +* Before this update, an incorrect private key containing certificate data caused HAProxy reload failure in {product-title} 4.14. As a consequence, incorrect certificate configuration caused HAProxy router pods to fail reloads, which led to a partial outage. With this release, `haproxy` now validates certificates. As a result, router reload failures with invalid certificates are prevented. (link:https://issues.redhat.com/browse/OCPBUGS-49769[OCPBUGS-49769]) +``` + +### Z-stream fixed issue + +```asciidoc +* Before this update, the egress IP address was incorrectly assigned to the br-ex bridge when you configured additional interfaces. This issue caused egress IP address assignment conflicts and routing issues with unexpected traffic paths. With this release, the egress IP address is not assigned to the br-ex bridge. As a result, the egress IP address is correctly assigned to the secondary interface, which resolves routing conflicts. (link:https://redhat.atlassian.net/browse/OCPBUGS-77257[OCPBUGS-77257]) +``` + +### Z-stream enhancement (with continuation) + +```asciidoc +* With this release, the Insights Operator now collects the `opentelemetrycollectors.opentelemetry.io` custom resource to improve data retrieval efficiency and system performance. ++ +To maintain security and prevent the collection of sensitive information, the Insights Operator applies the following constraints: + +** Resource Limit: The Insights Operator collects a maximum of five OpenTelemetry Collector custom resources from the cluster. + +** Data Masking: The Insights Operator retains only the service subsection of the `spec.config` field. It omits receivers, exporters, and other pipeline configuration details. ++ +These improvements allow {product-title} to better analyze the efficiency of the data gathering process and provide more precise environment insights. (link:https://redhat.atlassian.net/browse/OCPBUGS-79534[OCPBUGS-79534]) ``` ## Integration with other skills From ecfa60a9b29d78c080b615b9e6c5c82d1ea4c6c0 Mon Sep 17 00:00:00 2001 From: Kevin Quinn <kquinn@redhat.com> Date: Tue, 28 Apr 2026 10:18:30 +0100 Subject: [PATCH 08/11] docs: add README for release-notes-writer skill Explains the three input modes (PR URL, JIRA key, Release Note Type), supported change types, example output, and style conventions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- .../skills/release-notes-writer/README.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 plugins/docs-tools/skills/release-notes-writer/README.md diff --git a/plugins/docs-tools/skills/release-notes-writer/README.md b/plugins/docs-tools/skills/release-notes-writer/README.md new file mode 100644 index 00000000..0da0e2d0 --- /dev/null +++ b/plugins/docs-tools/skills/release-notes-writer/README.md @@ -0,0 +1,119 @@ +# Release Notes Writer + +Generate user-centric release notes for OpenShift features in AsciiDoc format. The skill reads GitHub PRs or JIRA tickets, classifies the change type, and outputs a copy-paste-ready release note entry that follows OCP repo conventions. + +## Prerequisites + +- **Claude Code** with the `docs-tools` plugin installed +- **GITHUB_TOKEN** environment variable set (for reading PRs) +- **JIRA access** configured via the `jira-mcp` MCP server (for reading JIRA tickets) + +## How to use + +There are three ways to invoke this skill. In each case, Claude reads the source material, classifies the change, and drafts the release note using the correct template. + +### 1. Point it at a GitHub PR + +If you have a PR that describes a new feature or enhancement, pass the PR URL: + +``` +/release-notes-writer https://github.com/openshift/openshift-docs/pull/12345 +``` + +The skill reads the PR title, description, and diff, then drafts a **New Feature** release note entry. + +### 2. Point it at a JIRA ticket by key + +Pass a JIRA issue key directly: + +``` +/release-notes-writer OCPBUGS-12345 +``` + +Or use the full URL: + +``` +/release-notes-writer https://issues.redhat.com/browse/CNF-5678 +``` + +The skill reads the JIRA summary, description, and the **Release Note Type** field to determine which template to use. + +### 3. How the JIRA "Release Note Type" field maps to output + +The **Release Note Type** field on the JIRA ticket controls which template the skill applies: + +| Release Note Type | What the skill generates | +|---|---| +| **Feature** or **Enhancement** | New feature entry (definition list format) | +| **Bug Fix** | Fixed issue entry (bullet format) | +| **Known Issue** | Known issue entry (bullet format) | + +You can also provide additional context or instructions alongside the URL or key: + +``` +/release-notes-writer OCPBUGS-12345 — this is for the 4.19 z-stream +``` + +## What you get back + +The skill outputs an AsciiDoc block that you can paste directly into the appropriate release notes file. The format depends on the change type. + +### New feature example + +```asciidoc +// CNF-5678 +PTP grandmaster clock support:: ++ +You can now configure a PTP grandmaster clock on bare-metal nodes. +This enables sub-microsecond time synchronization across your cluster. ++ +For more information, see xref:../networking/ptp/ptp-grandmaster.adoc#configuring-grandmaster[Configuring a PTP grandmaster clock]. +``` + +### Bug fix example + +```asciidoc +* Before this update, the egress IP address was incorrectly assigned + to the br-ex bridge. As a consequence, routing conflicts occurred. + With this release, the egress IP address is correctly assigned to + the secondary interface. As a result, routing conflicts are resolved. + (link:https://issues.redhat.com/browse/OCPBUGS-77257[OCPBUGS-77257]) +``` + +### Known issue example + +```asciidoc +* Currently, on clusters with SR-IOV virtual functions configured, + a race condition might occur between system services and the TuneD + service. As a consequence, the TuneD profile might become degraded + after a node restart. As a workaround, restart the TuneD pod to + restore the profile state. + (link:https://issues.redhat.com/browse/OCPBUGS-41934[OCPBUGS-41934]) +``` + +## Supported change types + +The skill handles six types of release note entries: + +1. **New feature or enhancement** -- Definition list format with "what you can now do" and "why it matters" +2. **Bug fix (fixed issue)** -- Bullet format using the Before / Consequence / Fix / Result pattern +3. **Known issue** -- Bullet format with problem, consequence, and optional workaround +4. **Deprecated feature** -- Bullet format with deprecation notice and alternative +5. **Technology Preview to GA** -- Definition list format noting the TP-to-GA transition +6. **Z-stream (maintenance release)** -- Separate module format with fixed header and boilerplate + +## Style conventions applied + +- Second person ("you can", "your cluster"), active voice, present tense +- 3-5 sentences per entry, maximum two paragraphs +- No filler, hedging, or corporate-speak +- JIRA tracking comment above each entry +- Clickable JIRA links using `link:https://issues.redhat.com/browse/...` +- Cross-references using `xref:../` paths (relative from `modules/` directory) + +## Tips + +- **Multiple features in one PR**: The skill creates a separate entry for each distinct feature it identifies in the diff. +- **Missing JIRA ID**: The skill extracts the JIRA ID from the PR title, description, or branch name. If it can't find one, it will ask you. +- **Review after drafting**: Consider running `/rh-ssg-release-notes` on the output to verify SSG compliance. +- **Z-stream notes**: Mention "z-stream" in your prompt so the skill uses the maintenance release template instead of the GA format. From e06aa29bdb4a50fafcea521a11477c18044b1dc3 Mon Sep 17 00:00:00 2001 From: Kevin Quinn <kquinn@redhat.com> Date: Tue, 28 Apr 2026 10:35:23 +0100 Subject: [PATCH 09/11] fix: address CodeRabbit review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix typo: HostFirmareSettings → HostFirmwareSettings in SKILL.md - Reduce rh-ssg-release-notes allowed-tools to Read, Glob, Grep (least privilege for review-only skill) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- plugins/docs-tools/skills/release-notes-writer/SKILL.md | 2 +- plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 2d2aced5..15a1b634 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -281,7 +281,7 @@ The following additional VCF and VVF components are outside the scope of Red Hat ```asciidoc Running firmware upgrades for hosts in deployed bare metal clusters (Generally Available):: + -For hosts in deployed bare metal clusters, you can update firmware attributes and the firmware image. As a result, you can run firmware upgrades and update BIOS settings for hosts that are already provisioned without fully deprovisioning them. Performing a live update to the `HostFirmwareComponents`, `HostFirmareSettings`, or `HostUpdatePolicy` resource can be a destructive and destabilizing action. Perform these updates only after careful consideration. +For hosts in deployed bare metal clusters, you can update firmware attributes and the firmware image. As a result, you can run firmware upgrades and update BIOS settings for hosts that are already provisioned without fully deprovisioning them. Performing a live update to the `HostFirmwareComponents`, `HostFirmwareSettings`, or `HostUpdatePolicy` resource can be a destructive and destabilizing action. Perform these updates only after careful consideration. + This feature was introduced in {product-title} 4.18 with Technology Preview status. This feature is now supported as generally available in {product-title} {product-version}. + diff --git a/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md b/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md index c511e2f6..24c45b9d 100644 --- a/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md +++ b/plugins/docs-tools/skills/rh-ssg-release-notes/SKILL.md @@ -1,7 +1,7 @@ --- name: rh-ssg-release-notes description: "Review Red Hat release notes for SSG compliance — tense rules (present default, past for \"before this update\"), informative headings (sentence case, no gerunds, under 120 chars), Jira references on known/fixed issues, AsciiDoc formatting (description lists, + attachment), and release note types: new features, enhancements, rebases (X.Y.Z format), Technology Preview entries, deprecated features, removed features, known issues (Cause > Consequence > Workaround > Result), and fixed issues (CCFR pattern). Use this skill whenever reviewing, writing, or checking release notes for any Red Hat product." -allowed-tools: Read, Glob, Grep, Edit, Bash +allowed-tools: Read, Glob, Grep --- # Red Hat SSG: Release Notes review skill From 0a80b94f80c221aae3b84c8cc03f5f4d97d83051 Mon Sep 17 00:00:00 2001 From: Kevin Quinn <kquinn@redhat.com> Date: Fri, 1 May 2026 10:22:55 +0100 Subject: [PATCH 10/11] fix: remove unused WebFetch tool and add clickable JIRA link to deprecated template Addresses remaining CodeRabbit review comments: removes WebFetch from allowed-tools (not used by the skill) and uses the standard clickable link format in the deprecated feature template. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- plugins/docs-tools/skills/release-notes-writer/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/docs-tools/skills/release-notes-writer/SKILL.md b/plugins/docs-tools/skills/release-notes-writer/SKILL.md index 15a1b634..8cde069f 100644 --- a/plugins/docs-tools/skills/release-notes-writer/SKILL.md +++ b/plugins/docs-tools/skills/release-notes-writer/SKILL.md @@ -1,7 +1,7 @@ --- name: release-notes-writer description: Generate user-centric release notes for OpenShift telco features from GitHub PR content. Reads PR diffs, applies structured templates, and outputs AsciiDoc release note entries. -allowed-tools: Read, Bash, Grep, Glob, Agent, WebFetch +allowed-tools: Read, Bash, Grep, Glob, Agent --- # Release Notes Writer @@ -114,7 +114,7 @@ Format: ```asciidoc // <JIRA-ID> -* In this release, <what is deprecated>. <What to use instead or what direction the product is taking>. (<JIRA-ID>) +* In this release, <what is deprecated>. <What to use instead or what direction the product is taking>. (link:https://issues.redhat.com/browse/<JIRA-ID>[<JIRA-ID>]) ``` ### Technology Preview to GA From 8239d870e3d906277e15080e2768260d6619f0b4 Mon Sep 17 00:00:00 2001 From: Kevin Quinn <kquinn@redhat.com> Date: Fri, 1 May 2026 10:34:00 +0100 Subject: [PATCH 11/11] chore: remove redundant README.md from release-notes-writer skill The README duplicates content already in SKILL.md and wastes ~1,154 tokens of context window when agents load the skill directory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- .../skills/release-notes-writer/README.md | 119 ------------------ 1 file changed, 119 deletions(-) delete mode 100644 plugins/docs-tools/skills/release-notes-writer/README.md diff --git a/plugins/docs-tools/skills/release-notes-writer/README.md b/plugins/docs-tools/skills/release-notes-writer/README.md deleted file mode 100644 index 0da0e2d0..00000000 --- a/plugins/docs-tools/skills/release-notes-writer/README.md +++ /dev/null @@ -1,119 +0,0 @@ -# Release Notes Writer - -Generate user-centric release notes for OpenShift features in AsciiDoc format. The skill reads GitHub PRs or JIRA tickets, classifies the change type, and outputs a copy-paste-ready release note entry that follows OCP repo conventions. - -## Prerequisites - -- **Claude Code** with the `docs-tools` plugin installed -- **GITHUB_TOKEN** environment variable set (for reading PRs) -- **JIRA access** configured via the `jira-mcp` MCP server (for reading JIRA tickets) - -## How to use - -There are three ways to invoke this skill. In each case, Claude reads the source material, classifies the change, and drafts the release note using the correct template. - -### 1. Point it at a GitHub PR - -If you have a PR that describes a new feature or enhancement, pass the PR URL: - -``` -/release-notes-writer https://github.com/openshift/openshift-docs/pull/12345 -``` - -The skill reads the PR title, description, and diff, then drafts a **New Feature** release note entry. - -### 2. Point it at a JIRA ticket by key - -Pass a JIRA issue key directly: - -``` -/release-notes-writer OCPBUGS-12345 -``` - -Or use the full URL: - -``` -/release-notes-writer https://issues.redhat.com/browse/CNF-5678 -``` - -The skill reads the JIRA summary, description, and the **Release Note Type** field to determine which template to use. - -### 3. How the JIRA "Release Note Type" field maps to output - -The **Release Note Type** field on the JIRA ticket controls which template the skill applies: - -| Release Note Type | What the skill generates | -|---|---| -| **Feature** or **Enhancement** | New feature entry (definition list format) | -| **Bug Fix** | Fixed issue entry (bullet format) | -| **Known Issue** | Known issue entry (bullet format) | - -You can also provide additional context or instructions alongside the URL or key: - -``` -/release-notes-writer OCPBUGS-12345 — this is for the 4.19 z-stream -``` - -## What you get back - -The skill outputs an AsciiDoc block that you can paste directly into the appropriate release notes file. The format depends on the change type. - -### New feature example - -```asciidoc -// CNF-5678 -PTP grandmaster clock support:: -+ -You can now configure a PTP grandmaster clock on bare-metal nodes. -This enables sub-microsecond time synchronization across your cluster. -+ -For more information, see xref:../networking/ptp/ptp-grandmaster.adoc#configuring-grandmaster[Configuring a PTP grandmaster clock]. -``` - -### Bug fix example - -```asciidoc -* Before this update, the egress IP address was incorrectly assigned - to the br-ex bridge. As a consequence, routing conflicts occurred. - With this release, the egress IP address is correctly assigned to - the secondary interface. As a result, routing conflicts are resolved. - (link:https://issues.redhat.com/browse/OCPBUGS-77257[OCPBUGS-77257]) -``` - -### Known issue example - -```asciidoc -* Currently, on clusters with SR-IOV virtual functions configured, - a race condition might occur between system services and the TuneD - service. As a consequence, the TuneD profile might become degraded - after a node restart. As a workaround, restart the TuneD pod to - restore the profile state. - (link:https://issues.redhat.com/browse/OCPBUGS-41934[OCPBUGS-41934]) -``` - -## Supported change types - -The skill handles six types of release note entries: - -1. **New feature or enhancement** -- Definition list format with "what you can now do" and "why it matters" -2. **Bug fix (fixed issue)** -- Bullet format using the Before / Consequence / Fix / Result pattern -3. **Known issue** -- Bullet format with problem, consequence, and optional workaround -4. **Deprecated feature** -- Bullet format with deprecation notice and alternative -5. **Technology Preview to GA** -- Definition list format noting the TP-to-GA transition -6. **Z-stream (maintenance release)** -- Separate module format with fixed header and boilerplate - -## Style conventions applied - -- Second person ("you can", "your cluster"), active voice, present tense -- 3-5 sentences per entry, maximum two paragraphs -- No filler, hedging, or corporate-speak -- JIRA tracking comment above each entry -- Clickable JIRA links using `link:https://issues.redhat.com/browse/...` -- Cross-references using `xref:../` paths (relative from `modules/` directory) - -## Tips - -- **Multiple features in one PR**: The skill creates a separate entry for each distinct feature it identifies in the diff. -- **Missing JIRA ID**: The skill extracts the JIRA ID from the PR title, description, or branch name. If it can't find one, it will ask you. -- **Review after drafting**: Consider running `/rh-ssg-release-notes` on the output to verify SSG compliance. -- **Z-stream notes**: Mention "z-stream" in your prompt so the skill uses the maintenance release template instead of the GA format.