WIP: MTA-6826, 6827, 6828, 6829, 6830, 6831 CQA April work for rules development guide#359
WIP: MTA-6826, 6827, 6828, 6829, 6830, 6831 CQA April work for rules development guide#359Pkylas007 wants to merge 11 commits into
Conversation
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughDocumentation-only edits across the Rules Development guide: replaced hardcoded product/CLI names with parameterized placeholders, reordered Asciidoc conditionals, renamed/retitled provider labels and inline code formatting, removed one rule-conditions include, and updated a cross-reference target. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/topics/rules-development/yaml-java-locations.adoc (1)
114-123:⚠️ Potential issue | 🟠 MajorAlign location keyword with example (
FIELDvsFIELD_DECLARATION).Line 114 lists
FIELD, but the example at Lines 121-123 usesFIELD_DECLARATION. Please make these consistent; otherwise readers may use an invalid location value in rules.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/topics/rules-development/yaml-java-locations.adoc` around lines 114 - 123, The location keyword is inconsistent: the table lists `FIELD` but the example uses `FIELD_DECLARATION`; update one so both match. Edit the example in the java.referenced block or the table entry so the location value is the same (choose either `FIELD` or `FIELD_DECLARATION`) and ensure the example's when -> java.referenced -> location uses that exact token; keep the rest (pattern: javax.jms.QueueConnectionFactory) unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/topics/rules-development/yaml-dotnet-provider.adoc`:
- Line 12: Replace the standalone acronym "gRPC" in the sentence that begins
"The `C#` provider uses a gRPC interface..." by expanding it on first use as
"Google Remote Procedure Call (gRPC)" and then retain the abbreviation "gRPC"
for subsequent mentions; update the sentence containing the term `gRPC` so it
reads with the full name followed by the abbreviation.
In `@docs/topics/rules-development/yaml-java-locations.adoc`:
- Line 146: The DESCRIPTION for the `CLASS` declaration is wrong: update the row
that reads "`CLASS` (declaration) Matches against a given method declaration" to
describe class declarations instead—e.g., say "`CLASS` (declaration) Matches
against a given class declaration; can be coupled with an annotation match (see
Annotation inspection)". Modify the text for the `CLASS` entry in
yaml-java-locations.adoc to replace "method declaration" with "class
declaration" and keep the note about coupling with annotations/reference to the
Annotation inspection page.
In `@docs/topics/rules-development/yaml-provider-conditions.adoc`:
- Around line 325-329: The row describing the `builtin.json` capability uses the
phrase "an XPath query" which conflicts with earlier terminology (`jsonpath`);
update the phrase "an XPath query" to "a JSONPath query" (or "a jsonpath
expression") so the `builtin.json` row consistently references JSONPath/jsonpath
like the earlier JSON capability text.
---
Outside diff comments:
In `@docs/topics/rules-development/yaml-java-locations.adoc`:
- Around line 114-123: The location keyword is inconsistent: the table lists
`FIELD` but the example uses `FIELD_DECLARATION`; update one so both match. Edit
the example in the java.referenced block or the table entry so the location
value is the same (choose either `FIELD` or `FIELD_DECLARATION`) and ensure the
example's when -> java.referenced -> location uses that exact token; keep the
rest (pattern: javax.jms.QueueConnectionFactory) unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 67d7ee91-99a7-4c2f-a69a-16d41e10c933
📒 Files selected for processing (7)
assemblies/rules-development-guide/assembly_creating-rule.adocassemblies/rules-development-guide/assembly_java-conditions-detailed.adocassemblies/rules-development-guide/assembly_rules-introduction.adocdocs/topics/rules-development/yaml-dotnet-provider.adocdocs/topics/rules-development/yaml-java-locations.adocdocs/topics/rules-development/yaml-provider-conditions.adocdocs/topics/rules-development/yaml-rule-conditions.adoc
💤 Files with no reviewable changes (1)
- docs/topics/rules-development/yaml-rule-conditions.adoc
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Pkylas007
changed the title
Pkylas007
changed the title
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
JIRA CQA Analysis and Remediation Summary: PR #359Document Title: Configuring and using rules for an MTA analysis Analysis Date: 2026-04-15 Genuine Issues Identified: 10 Pull Request #359 successfully addresses the genuine issues identified in the April 2026 Content Quality Assurance (CQA) report by remediating findings across six JIRA issues (MTA-6826 to MTA-6831). 1. Critical Structural Repairs (MTA-6826)This JIRA issue focuses on structural integrity and orphaned files.
2. Branding and Attribute Compliance (MTA-6827)This JIRA issue ensures product naming meets branding standards.
3. Technical Formatting and Accuracy (MTA-6828)This JIRA issue standardizes YAML properties and provider names.
4. Readability and Grammar Remediation (MTA-6829)This JIRA issue targets dense prose and passive construction.
5. Clarity and Style Standardization (MTA-6830 & MTA-6831)These JIRA issues cover acronym definitions and overall style polish.
|
anarnold97
left a comment
anarnold97
left a comment
There was a problem hiding this comment.
DITA report
master.adoc
-
12:1 warning Assign [role="_abstract"] AsciiDocDITA.ShortDescription
to a paragraph to use it as
in DITA. -
12:1 warning Content other than additional AsciiDocDITA.AssemblyContents
resources cannot follow
include directives. -
39:1 warning Content other than links AsciiDocDITA.RelatedLinks
cannot be mapped to DITA
related-links.Are these all false positives?
Hey Andy,
|
vashirova
left a comment
vashirova
left a comment
There was a problem hiding this comment.
@Pkylas007 peer review completed, see my comments. This is a great start! I've noticed some outstanding issues that are applicable to several files:
- Abstracts - some of them exceed character limit of 300, end with a colon (:), and do not work as standalone text.
- Leftover "refer to" instances.
- Complex ifdef syntax in assemblies.
- Leftover inconsistencies in "rule sets" spelling.
- Leftover passive voice.
- Broken syntax for italics.
- Leftover incorrectly formatted user-replaced values (must be <user_replaced>).
- Not everything from the linked ticket was addressed.
Let me know when you'd need a second round of review. Thank you.
There was a problem hiding this comment.
Outside of scope suggestions for this and other files but must before migration to AEM:
- Rewrite abstract to clarify wording 'capability in the when condition' (when in backticks perhaps?) plus colon (:) is not supported for short description in AEM. See https://redhat-documentation.github.io/supplementary-style-guide/#_core_principles_for_writing_a_helpful_short_description.
- Replace 'refer to' (for example, with 'see'). See https://www.ibm.com/docs/en/ibm-style?topic=word-usage#r.
There was a problem hiding this comment.
Outside of scope suggestions but a must before migration to AEM:
- Shorten/add a new paragraph for abstract as the current one is a bit too long (394 characters instead of 300).
- Also, it is not standalone text, "Additionally..." right afterwards suggests this. I'd recommend to rework this - either to rewrite the current abstract and following text or add a completely new and separate 300 characters short description. See https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc.
|
|
||
| The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the {mta-dl-plugin} to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis. | ||
|
|
||
| The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. {mta-dl-plugin} uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that {ProductShortName} identified through an analysis. |
There was a problem hiding this comment.
How about this rewrite for the first sentence to remove passive voice?
Plus there are more instances of passive voice in this files and others, too. Is it intentional that we are fixing only this specific instance and not everything?
| The rules can be used by {mta-dl-plugin} to generate AI-assisted code resolutions. {mta-dl-plugin} uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that {ProductShortName} identified through an analysis. | |
| {mta-dl-plugin} can use the rules to generate AI-assisted code resolutions. It uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that {ProductShortName} identified through an analysis. |
|
|
||
| :_mod-docs-content-type: ASSEMBLY | ||
|
|
||
| ifdef::context[:parent-context-of-java-conditions-capabilities: {context}] |
There was a problem hiding this comment.
I'm not entirely sure what we are trying to achieve with this change, could you elaborate on it please
Furthermore, the ifdef syntax with 2 statements seems complex. Typically we'd use ifdef if an assembly is re-used, however I don't think any of the assemblies in this PR are re-used right now? Could we review all this ifdef syntax for all of assemblies and asses if it could be simplified or removed? This could help with the unclosed parent context issue.
There was a problem hiding this comment.
Thank you for your comment. I'm sorry but the CQA and DITA runs did not catch any unclosed parent context issue. I think the unset issue that is flagged was a false positive.
There was a problem hiding this comment.
I like that this short description includes the who and the what. The only missing piece according to our guidance https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc is missing user-focused language ("This guide is intended " is self-referential and must be avoided). I suggest to reword it for DITA.
|
|
||
| * You installed the `ilspycmd` and `paket` dependencies. | ||
| * You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:<path/to/.dotnet/tools"` command. | ||
| * You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:_<path_to_.dotnet_tools>_"` command. |
There was a problem hiding this comment.
The newly added underscores do not make this user-replaceable value in italic, I'm not sure why. Perhaps we can try double underscores to read it as one piece?
| * You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:_<path_to_.dotnet_tools>_"` command. | |
| * You installed the `dotnet tools` and exported the `dotnet tools` path by using the `export PATH="$PATH:__<path_to_.dotnet_tools>__"` command. |
There was a problem hiding this comment.
I agree, the formatting requirements seem complicated and make rendering very tricky.
| @@ -62,7 +62,7 @@ You can use a custom rule to check if {ProductShortName} triggers an incident wh | |||
|
|
|||
| [source, terminal] | |||
There was a problem hiding this comment.
| [source, terminal] | |
| [source, terminal,subs="+quotes"] |
Changes on line 65 do not work, the user-replaced value is not in italics.
|
|
||
| [role="_abstract"] | ||
| You can refer to example rules that describe how to create a YAML rule. This assumes that you already have MTA installed. See the MTA CLI Guide for installation instructions. | ||
| You can refer to example rules that describe how to create a YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {CLIName} Guide for installation instructions. |
There was a problem hiding this comment.
I believe this abstract can be improved. First of all, it again uses "refer to" which isn't recommended for docs in general, see https://www.ibm.com/docs/en/ibm-style?topic=word-usage#r. Second, we can be more direct and start with an imperative. Next, as a general rule, I'd argue that referring users to another piece of documentation doesn't belong in short descriptions. Short descriptions meant to help user navigate and should work as a standalone piece. I strongly suggest to review this and other short descriptions.
| |Location |Description |Rule condition example | ||
|
|
||
| |TYPE|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere. | ||
| |`TYPE`|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere. |
There was a problem hiding this comment.
| |`TYPE`|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere. | |
| |`TYPE`|Matches against all types, including classes, interfaces, `enums`, and annotation types that appear anywhere. |
| mkdir /home/<USER>/data/ | ||
| touch /home/<USER>/data/jboss-web.xml | ||
| touch /home/<USER>/data/pom.xml |
There was a problem hiding this comment.
This happens to catch my eye. These commands should be separated (one command per one command block) and shell prompt (I think $, based on the previous step) should be added to each.
There was a problem hiding this comment.
Thank you for your suggestion! This topic requires a re-write which is not strictly within the scope of work tracked in this PR. I'll get back to you on this 👍
|
Also can we be careful when running DITA output: I think as the Also, I know Thanks |
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Thanks for the comment. Previously, the team agreed that The |
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
Pkylas007
changed the title
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
I disagree with the last point. I made sure that all points in the JIRA were covered. Many review comments are out of scope in the review compared with the JIRA tasks. I think the review was not done keeping in mind the scope of issues in JIRA. For the next review, please refer to my guidance on which JIRA changes are false positives and which suggestions can' t be applied in the content. Happy to help! Thank you. |
| To analyze applications in `Python`, `Node.js`, `Go`, and `C#`, the Architect must create a custom rule. A custom rule includes conditions and patterns that describe an issue. You must resolve issues when refactoring applications before migrating them to a target platform. | ||
|
|
||
| //This section describes how to create a {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.// | ||
| You can see examples that describe how to create a custom rule. This assumes that you already installed {ProductShortName}. See the {ProductShortName} {CLIName} Guide for installation instructions. |
There was a problem hiding this comment.
Abstract Formatting (Single Paragraph) The Content Quality Assessment (CQA) guidelines explicitly state that a short description introduced with [role="_abstract"] must be a single paragraph between 50 and 300 characters
. Your current text is split across two paragraphs, which violates this rule.
There was a problem hiding this comment.
I'm still addressing the latter part of this guide. Please understand that this PR is work in progress and is not sent out for review.
The tone of the language in review comments is unacceptable.
| The `java.referenced` capability in the when condition for Java rules can define search queries for the following fields in the source code: | ||
| An Architect can create custom rules to search for problematic patterns in the `Java` source code when preparing an application for migration to a target platform. | ||
|
|
||
| The Language Server used by the `Java` provider is Eclipse's Java Development Tools Language Server (JDTLS). Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects. |
There was a problem hiding this comment.
"Eclipse's": You used an apostrophe and an "s" to form a possessive product/brand name. The style guidelines explicitly prohibit using the possessive form for brand or product names
- Change this to "the Eclipse Java Development Tools Language Server".
|
|
||
| You can use the `java.referenced` capability in the `when` condition of the `Java` rules to search for the following fields: | ||
|
|
||
| * Locations - such as the classes, methods, packages and so on |
There was a problem hiding this comment.
"Locations - such as...": You used a hyphen/dash to introduce an explanatory phrase. The IBM Style guide states that you must not use em dashes (or freestanding hyphens used as dashes) in technical information
. Use a comma instead.
| @@ -16,13 +14,17 @@ endif::[] | |||
| :context: java-conditions-capabilities | |||
|
|
|||
| [role="_abstract"] | |||
There was a problem hiding this comment.
Abstract Formatting (Single Paragraph) The CQA guidelines explicitly state that a short description introduced with the [role="_abstract"] tag must be a single paragraph between 50 and 300 characters
. Currently, your draft groups multiple paragraphs and a list under the abstract role. You should leave only the first paragraph as the abstract, and treat the rest of the content as standard body text
.
There was a problem hiding this comment.
The abstract tag only has a single para that follows it. All other content start from the next para. Not sure what is being flagged here.
| :context: logical-chaining-custom-variables | ||
|
|
||
| [role="_abstract"] | ||
| When you create a rule, you can scope down the search query in the source code by using logical conditions, condition chaining, nested conditions, and custom variables. The scope limits the search to a specific file, a pattern, or a combination of conditions. |
There was a problem hiding this comment.
-
Abstract Formatting (Single Paragraph) The CQA guidelines explicitly state that a short description introduced with the [role="_abstract"] tag must be a single paragraph between 50 and 300 characters. Currently, your text groups multiple paragraphs and a list directly under the abstract. You should leave only the first paragraph as the abstract, and treat the rest of the content (starting with "You can create complex conditions...") as standard body text.
-
Word Choice ("scope down") You used the phrase "scope down". The IBM Style guide dictates that you should avoid using phrasal verbs (a verb plus a preposition) if a single, more precise verb provides the same meaning. Change "scope down" to "narrow" or "limit".
-
Highlighting (Code Elements) You correctly used backticks around
andandorbecause they refer to specific code parameters. However, you missed the word "when" in the phrase "in a when block". Because this refers to a specific programming block or keyword, you must apply monospace formatting and write it as "whenblock". -
List Formatting and Scannability
List introduction: To avoid translation problems, IBM style requires that you use a complete sentence to introduce a list. Your introductory sentence is good, but you should change it slightly to "You can create complex conditions in rules by using the following methods:" to make it a fully complete thought.
Bold lead-ins: To improve scannability and adhere to minimalism principles, apply bold formatting to the term you are defining at the start of the bullet point.
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
3 participants
JIRA
Version
Preview
Summary by CodeRabbit