CQA 2.1: Rules Development Guide Feb 26

[anarnold97]

CQA Rules Development Guide — Summary Report

---

CQA - Rules Development Summary

Content set: Rules Development Guide (docs/rules-development-guide and included assemblies/topics)
Assessment standard: CQA 2.1 (Pre-migration and Quality)
Tools: Vale with Red Hat and AsciiDocDITA (DITA) styles only
Outcome: 0 errors, 0 warnings in 49 files

---

What Was Done

1. Assembly (master.adoc)

• Short description: Added an explicit short description paragraph with [role="_abstract"] so the guide has a clear DITA-style shortdesc (why the user should read the content).
• Content-type attribute: Set :_mod-docs-content-type: ASSEMBLY so the assembly is correctly typed for migration.
• Additional resources: Reworked the list so it contains only links (no leading text before the link). Entries are now in the form * link:...[...] and * link:mailto:...[...] so they map cleanly to DITA related-links.

2. Procedure (create-first-yaml-rule.adoc)

• Procedure block title: Added a .Procedure block title above the ordered list of steps so the task structure matches the expected procedure pattern.

3. Red Hat style and terms (topic modules)

• Hyphens: In about-rules.adoc, changed “plug-ins” to “plugins” per Red Hat style.
• Using: In yaml-custom-variables.adoc and yaml-java-provider.adoc, changed “using” to “by using” where it follows a noun (e.g. “message by using”, “code by using a query”).
• Case-sensitive terms: In yaml-java-provider.adoc, changed “(url = …)” to “(URL = …)” in the annotation example description.
• Slash: In yaml-java-provider.adoc, rephrased “external/open source” to “external or open source” to avoid a slash between alternatives.
• Terms: In yaml-dotnet-provider.adoc, changed “the desired reference” to “the required reference” to align with preferred wording.
• Built-in: (from earlier CQA pass) In assembly_rule-yaml-conditions.adoc and yaml-builtin-provider.adoc, replaced “Builtin” with “built-in” and used the heading “Built-in provider.”

4. Spelling (technical and API terms)

Technical and product terms used in the rules-development content were added to the Red Hat spelling allowlist so they are not flagged as misspellings. Examples include: XPath, JSONPath, xml, xpath, uppercased, filecontent, hasTags, nameregex, upperbound, lowerbound, filepaths, filePattern, enums, FQNs, informat, json, and related variants. No change was made to the visible content for these terms; only the spelling checks were adjusted to accept them.

---

Scope of the rules-development guide

The assessed set includes:

• Master: docs/rules-development-guide/master.adoc
• Shared/templates: topics/templates/document-attributes.adoc, topics/making-open-source-more-inclusive.adoc
• Assemblies: All 8 assemblies under assemblies/rules-development-guide/
• Topics: All modules under topics/rules-development/ that are included by those assemblies

Total: 49 files.

---

Result

• Vale (Red Hat + AsciiDocDITA): 0 errors, 0 warnings, 0 suggestions.
• CQA 2.1 pre-migration: The requirement that content passes the Vale asciidoctor-dita-vale check with no errors or warnings is met.

[coderabbitai]

Warning

Rate limit exceeded

@anarnold97 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 31 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

This PR updates YAML rule development documentation with terminology standardization (e.g., "Builtin" to "Built-in"), wording refinements for clarity, metadata attributes, link macro formatting, and a new step-by-step procedural section for creating and testing a YAML-based rule.

Changes

Cohort / File(s)	Summary
Terminology & Wording Updates assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc, docs/topics/rules-development/about-rules.adoc, docs/topics/rules-development/yaml-builtin-provider.adoc, docs/topics/rules-development/yaml-custom-variables.adoc, docs/topics/rules-development/yaml-dotnet-provider.adoc, docs/topics/rules-development/yaml-java-provider.adoc	Minor textual refinements: "Builtin" → "Built-in", "IDE plug-ins" → "IDE plugins", "using a" → "by using a", "desired reference" → "required reference", and "external/open source" → "external or open source".
Documentation Structure & Metadata docs/rules-development-guide/master.adoc	Added _mod-docs-content-type: ASSEMBLY metadata attribute, renamed role attribute from "abstract" to "_abstract", added introductory sentence, and converted plain-text resource links to AsciiDoc link macros.
New Procedural Content docs/topics/rules-development/create-first-yaml-rule.adoc	Added comprehensive step-by-step Procedure section with instructions for creating a YAML rule file, supporting data files (jboss-web.xml, pom.xml), rule configuration structure, CLI usage guidance, and HTML report verification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 From Builtin to built-in we hop,
With IDE plugins that never stop,
New rules in YAML take their place,
Step-by-step guides light the race!
The docs now shine in structured grace. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is vague and does not clearly convey the specific changes made; it reads like a ticket reference with a date rather than describing the actual content modifications.	Consider using a more descriptive title that summarizes the main changes, such as 'Update Rules Development Guide documentation with terminology and formatting improvements' or 'Standardize documentation terminology: built-in provider and plugin references'.

✅ Passed checks (2 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.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

docs/topics/rules-development/create-first-yaml-rule.adoc (4)

15-20: ⚠️ Potential issue | 🟡 Minor

Use a file creation command (not mkdir) for rule.yaml.
mkdir creates a directory, so the subsequent steps will fail.

Suggested fix

-$ mkdir /home/<USER>/rule.yaml
+$ touch /home/<USER>/rule.yaml

---

109-114: ⚠️ Potential issue | 🟡 Minor

Fix YAML indentation for links example.
title should be nested under the list item, otherwise the YAML is invalid.

Suggested fix

-  links:
-    - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6
-  title: Create or Modify Files That Control Class Loading in JBoss EAP 6
+  links:
+    - url: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6
+      title: Create or Modify Files That Control Class Loading in JBoss EAP 6

---

132-137: ⚠️ Potential issue | 🟡 Minor

Command flag and filename are inconsistent.
Use a standard double hyphen and keep the filename consistent with rule.yaml.

Suggested fix

-–rules /home/<USER>/rules.yaml
+--rules /home/<USER>/rule.yaml

---

156-156: ⚠️ Potential issue | 🟡 Minor

Keep the home placeholder consistent.
<USER_NAME> is inconsistent with earlier <USER>.

Suggested fix

-Open `/home/<USER_NAME>/output/static-report/index.html` in a web browser.
+Open `/home/<USER>/output/static-report/index.html` in a web browser.

[mpershina]

A few changes needed. Otherwise, LGTM!

[Pkylas007]

Only two nits, otherwise LGTM.

Thank you!