April CQA work for MTA 8.1 Release Notes DITA fixes

[Pkylas007]

JIRA

• MTA-6806
• MTA-6807
• MTA-6808
• MTA-6809
• MTA-6810

Version

• 8.1

Preview

• Release Notes 8.1 and 8.0

Summary by CodeRabbit

• Documentation

  • Revised release-note wording for clarity and consistency (e.g., “open source”, “As a result”, “Visual Studio Code”, expanded IDE naming)
  • Standardized release-notes attribute key naming for consistent downstream processing

• Chores

  • Simplified and reorganized AsciiDoc conditional attribute handling and placement for more predictable rendering

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Updated AsciiDoc conditional guards to use version-specific parent-context-of-mta-* keys, standardized the module content-type attribute name to :_mod-docs-content-type: ASSEMBLY in assemblies and root release-notes, and applied multiple editorial wording tweaks across release-notes topic files.

Changes

Cohort / File(s)	Summary
Assembly context & content-type assemblies/release-notes/assembly_mta-8-0-0.adoc, assemblies/release-notes/assembly_mta-8-0-1.adoc, assemblies/release-notes/assembly_mta-8-0.adoc, assemblies/release-notes/assembly_mta-8-1-0.adoc	Replaced ifdef/ifndef guards that referenced parent-context-of-analyzing-multi-language-applications with version-specific parent-context-of-mta-* keys; adjusted :context: / :!context: assignments and inserted/standardized :_mod-docs-content-type: ASSEMBLY where applicable.
Docs release-notes root docs/release-notes/master.adoc	Renamed document attribute from :_content-type: ASSEMBLY to :_mod-docs-content-type: ASSEMBLY.
Release-notes topic edits (editorial) docs/topics/release-notes-topics/ref_fixed-issues-8-0-1.adoc, docs/topics/release-notes-topics/ref_fixed-issues-8-0.adoc, docs/topics/release-notes-topics/ref_new-features-and-enhancements-8-0.adoc, docs/topics/release-notes-topics/ref_removed-features-8-0.adoc, docs/topics/release-notes-topics/ref_dev-preview-8-1-0.adoc, docs/topics/release-notes-topics/ref_known-issues-8-0-1.adoc, docs/topics/release-notes-topics/ref_tech-previews-8-0.adoc	Editorial wording changes only (e.g., “VS Code” → “Visual Studio Code”, expand “IDEs”, “Consequently” → “As a result”, minor phrasing and heading adjustments). No structural or behavioral changes.

Sequence Diagram(s)

(omitted — changes are documentation/editorial and do not introduce multi-component control flow)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• [WIP] 8.1.0 MTA RNs #299: Modifies AsciiDoc release-note assemblies and conditional context/attribute handling (strong overlap with assembly guard and attribute changes).
• [April CQA] Install doc master.adoc and spacing fixes #351: Edits placement/handling of :_mod-docs-content-type around assembly/front-matter (closely related to attribute insertion/renaming).
• [April CQA] CQA and other fixes for MTA CLI  #354: Adjusts AsciiDoc metadata and content-type attribute usage (related attribute renaming/placement).

Suggested reviewers

• anarnold97
• mpershina
• jortel

Poem

🐰 I hop through docs with tidy little paws,
I swap context keys and smooth wording flaws.
From "VS Code" to "Visual" I nudge and cheer,
I set the assembly flag — all neat and clear. 🥕📘

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is partially related to the changeset. While it mentions 'Release Notes DITA fixes' and references 'April CQA work', the 'DITA fixes' framing does not accurately capture the primary nature of the changes, which are largely AsciiDoc attribute/conditional updates and documentation rewording, not DITA-specific fixes.	Clarify the title to better reflect the actual changes: consider 'Update AsciiDoc conditional logic and reword release notes documentation for MTA 8.1' or similar, to more accurately represent the attribute updates and content quality improvements.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mta-6806

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vashirova]

@Pkylas007, peer review completed. I've left some suggestions, see my notes. Overall I'd be careful in replacing all passive voice with active as many sentences start sounding anthropomorphic and otherwise odd. Plus I'd rework abstracts to make them fit bot DITA and Style Guides criteria (no self-referential text, consistency in wording, etc.).

@vashirova Thank you! The CQA recommendation for non-permitted passive voice is to re-write the sentences in active voice.

[vashirova]

@vashirova Thank you! I honestly think we are complicating DITA work with too many requirements. Let's not follow passive voice correction.

@Pkylas007 passive voice is our Style Guides requirements and thus must be fixed. I agree that it doesn't make sense to change all instances and we must evaluate all instances one by one. However if we are replacing passive voice, we should consider our style guides to not introduce other violations.

[Pkylas007]

RedHat style guide rules do not state that release notes headings must not have imperative verbs.

[vashirova]

RedHat style guide rules do not state that release notes headings must not have imperative verbs.

Actually the SSG is clear on that one. Imperative is to be used for procedural and task-based content and RNs do not fit here. See https://redhat-documentation.github.io/supplementary-style-guide/#titles-and-headings. Plus, for RNs specifically SSG says 'Follow the specifics for the release note type" https://redhat-documentation.github.io/supplementary-style-guide/#headings-for-release-notes. Imperative doesn't indicate what type of change it is, instead it calls to an action when we are just describing the change.

[Pkylas007]

RedHat style guide rules do not state that release notes headings must not have imperative verbs.

Actually the SSG is clear on that one. Imperative is to be used for procedural and task-based content and RNs do not fit here. See https://redhat-documentation.github.io/supplementary-style-guide/#titles-and-headings. Plus, for RNs specifically SSG says 'Follow the specifics for the release note type" https://redhat-documentation.github.io/supplementary-style-guide/#headings-for-release-notes. Imperative doesn't indicate what type of change it is, instead it calls to an action when we are just describing the change.

The SSG has a separate section for Release Notes headings and that section doesn't prohibit an imperative. It makes sense too: not to be too restrictive about how exactly the RN headings are written :)

[vashirova]

The SSG has a separate section for Release Notes headings and that section doesn't prohibit an imperative. It makes sense too: not to be too restrictive about how exactly the RN headings are written :)

While the RN section in SSG doesn't comment on imperative, the other linked section makes it clear. "Specify" in RNs makes the heading sound like an instruction for a procedure rather than a summary of a fixed bug. For fixed issues, the heading should be a declarative statement summarizing the resolution or the state of the product after the update. With imperative wording I cannot understand what's been changed. We should not be using imperative for any RNs headings.

[Pkylas007]

The SSG has a separate section for Release Notes headings and that section doesn't prohibit an imperative. It makes sense too: not to be too restrictive about how exactly the RN headings are written :)

While the RN section in SSG doesn't comment on imperative, the other linked section makes it clear. "Specify" in RNs makes the heading sound like an instruction for a procedure rather than a summary of a fixed bug. For fixed issues, the heading should be a declarative statement summarizing the resolution or the state of the product after the update. With imperative wording I cannot understand what's been changed. We should not be using imperative for any RNs headings.

Specify includes the fact that the user "can" specify: otherwise, the RN fixed bug section will not ask them to do so. Besides, the description makes it very clear what exactly has changed to enable the user to perform something. No? But for the sake of getting on with the task, I'll close this discussion 😄

[Pkylas007]

I have made all the required changes and attached the compressed result of the following test results in MTA-6806:

• CQA vale check
• CQA Asciidoctor check

[Pkylas007]

@anarnold97 please confirm if MTA-6231 in release notes must be moved to new features and enhancements section based on Dylan's clarification.

[anarnold97]

@anarnold97 Please confirm if MTA-6231 in release notes must be moved to new features and enhancements section based on Dylan's clarification.

@Pkylas007 - i did clarify on Friday, see HERE