Added copilot style guide for WSO2 IS#5898
Added copilot style guide for WSO2 IS#5898himeshsiriwardana wants to merge 2 commits intowso2:masterfrom
Conversation
WalkthroughThis PR overhauls documentation guidance and Vale linting: it replaces generic docs guidelines with a WSO2 Identity Server–specific authoring standard and removes most Microsoft and write-good Vale rules, consolidating linting around WSO2-IAM styles and adding a new formal-abbreviations rule. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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)
.github/skills/fix-documentation-issues/SKILL.md (1)
27-28:⚠️ Potential issue | 🟠 MajorContradictory style guide references after this PR.
Lines 27–28 mandate strict adherence to the Microsoft Style Guide for new and edited documentation, but this PR removes all Microsoft Vale rules from
.vale.iniand.vale/styles/Microsoft/, replacing them with WSO2-IAM-specific rules. Meanwhile,.github/copilot-instructions.mdestablishes a new WSO2 Identity Server–specific editorial standard. These instructions now conflict with the new copilot instructions and the Vale configuration.Consider updating these lines to reference the new WSO2 IS documentation standards in
.github/copilot-instructions.mdinstead of (or in addition to) the Microsoft Style Guide.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/skills/fix-documentation-issues/SKILL.md around lines 27 - 28, Replace the current absolute Microsoft Style Guide mandate text in the two lines with a clear reference to the WSO2 Identity Server documentation standards defined in .github/copilot-instructions.md (instead of the Microsoft Style Guide) and explicitly state the same scope: require full conformance for newly created documentation and only apply style updates to newly added content when editing existing docs; also note that Vale configuration now uses WSO2-IAM rules so the SKILL wording must align with the new .vale.ini and .vale/styles replacement.
🧹 Nitpick comments (2)
.github/skills/fix-documentation-issues/SKILL.md (1)
6-6:<!-- vale off -->disables all linting for this file — is that intentional?This suppresses all Vale checks on the SKILL.md content. Since the file contains prose guidelines (not just YAML/config), consider whether you actually want style enforcement here or if this is just to avoid noise from the skill instructions themselves.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/skills/fix-documentation-issues/SKILL.md at line 6, The file currently contains the global Vale suppression marker "<!-- vale off -->", which disables all linting for SKILL.md; remove that global marker or narrow its scope by replacing it with targeted Vale directives (e.g., disable only specific rules) or wrap only the exact prose block that must be excluded with matching "<!-- vale off -->" and "<!-- vale on -->" so style checks run on the rest of SKILL.md; ensure any replacement uses the Vale rule names you want to ignore rather than turning linting off entirely..github/copilot-instructions.md (1)
8-12: Good audience definition — aligns with repository learnings.The audience section covers the key personas (admins, developers, IT professionals) and sets the right baseline assumption level. Based on learnings: "Write documentation for multiple audiences: Developers (integrating the product), Testers/QA (verifying workflows), Support Engineers/Admins (troubleshooting), and Newcomers (onboarding)." You may want to explicitly mention testers/QA and newcomers as well for completeness.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/copilot-instructions.md around lines 8 - 12, Update the "### Audience" section to explicitly include Testers/QA and Newcomers alongside system administrators, developers, and IT professionals; edit the paragraph under the "### Audience" header to list these four personas (Developers, Testers/QA, Support Engineers/Admins, and Newcomers) and retain the baseline assumption about basic IT knowledge while calling out that newcomers may need additional onboarding detail.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/copilot-instructions.md:
- Line 281: Update the text string "When reviewing a pull request on Github,
check the output for adherence to all guidelines. Comment on any issues and
request changes if necessary." to use the correct capitalization "GitHub"
(capital H) so it reads "When reviewing a pull request on GitHub, check the
output for adherence to all guidelines. Comment on any issues and request
changes if necessary."; ensure any other occurrences of "Github" in the document
are also replaced with "GitHub".
- Around line 174-183: The "Heading capitalization rules" section contradicts
the "quality checklist" entry that says "Headings are title case"; pick one
style (either Sentence case or Title Case) and apply it consistently: update the
"Heading capitalization rules" heading and its example (the example string and
the bold mention of Sentence/Title case) and update the quality checklist entry
text that currently reads "Headings are title case" to match the chosen style;
ensure any examples, explanatory bullets, and the example heading string in that
section use the selected casing so both places are identical.
In @.vale.ini:
- Around line 11-16: The file contains dead overrides referencing removed
Microsoft rules: remove the lines "Microsoft.Headings = NO" and
"Microsoft.GeneralURL = No" from the .vale.ini sections (e.g., the [*.md] block
and the [**/restapis/**/*.yml] block) since BasedOnStyles no longer includes
Microsoft; ensure you keep other settings (BasedOnStyles, spelling,
TokenIgnores) intact and only delete those two Microsoft.* override entries.
---
Outside diff comments:
In @.github/skills/fix-documentation-issues/SKILL.md:
- Around line 27-28: Replace the current absolute Microsoft Style Guide mandate
text in the two lines with a clear reference to the WSO2 Identity Server
documentation standards defined in .github/copilot-instructions.md (instead of
the Microsoft Style Guide) and explicitly state the same scope: require full
conformance for newly created documentation and only apply style updates to
newly added content when editing existing docs; also note that Vale
configuration now uses WSO2-IAM rules so the SKILL wording must align with the
new .vale.ini and .vale/styles replacement.
---
Nitpick comments:
In @.github/copilot-instructions.md:
- Around line 8-12: Update the "### Audience" section to explicitly include
Testers/QA and Newcomers alongside system administrators, developers, and IT
professionals; edit the paragraph under the "### Audience" header to list these
four personas (Developers, Testers/QA, Support Engineers/Admins, and Newcomers)
and retain the baseline assumption about basic IT knowledge while calling out
that newcomers may need additional onboarding detail.
In @.github/skills/fix-documentation-issues/SKILL.md:
- Line 6: The file currently contains the global Vale suppression marker "<!--
vale off -->", which disables all linting for SKILL.md; remove that global
marker or narrow its scope by replacing it with targeted Vale directives (e.g.,
disable only specific rules) or wrap only the exact prose block that must be
excluded with matching "<!-- vale off -->" and "<!-- vale on -->" so style
checks run on the rest of SKILL.md; ensure any replacement uses the Vale rule
names you want to ignore rather than turning linting off entirely.
| [*.md] | ||
| BasedOnStyles = Microsoft, write-good, WSO2-IAM | ||
| BasedOnStyles = WSO2-IAM | ||
| spelling = yes | ||
| Microsoft.Headings = NO | ||
| Microsoft.GeneralURL = No | ||
| TokenIgnores = (\{%.+?%\})| (My Account portal)| (My Account) |
There was a problem hiding this comment.
Dead configuration: Microsoft.* overrides reference removed styles.
BasedOnStyles no longer includes Microsoft, and the Microsoft style files have been deleted in this PR. The Microsoft.Headings = NO and Microsoft.GeneralURL = No overrides on lines 14–15 now reference non-existent rules and should be removed to avoid confusion.
The same applies to lines 21–22 in the [**/restapis/**/*.yml] section.
Proposed fix
[*.md]
BasedOnStyles = WSO2-IAM
spelling = yes
-Microsoft.Headings = NO
-Microsoft.GeneralURL = No
TokenIgnores = (\{%.+?%\})| (My Account portal)| (My Account)
[**/restapis/**/*.yml]
BasedOnStyles = WSO2-IAM
-Microsoft.Headings = NO
-Microsoft.GeneralURL = No
Spelling = no🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.vale.ini around lines 11 - 16, The file contains dead overrides referencing
removed Microsoft rules: remove the lines "Microsoft.Headings = NO" and
"Microsoft.GeneralURL = No" from the .vale.ini sections (e.g., the [*.md] block
and the [**/restapis/**/*.yml] block) since BasedOnStyles no longer includes
Microsoft; ensure you keep other settings (BasedOnStyles, spelling,
TokenIgnores) intact and only delete those two Microsoft.* override entries.
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)
.github/skills/fix-documentation-issues/SKILL.md (1)
27-29:⚠️ Potential issue | 🟠 MajorClarify relationship between Microsoft Style Guide and WSO2 authoring standards.
These lines mandate adherence to the Microsoft Style Guide, but
.github/copilot-instructions.md(added in this same PR) defines comprehensive WSO2 Identity Server-specific authoring standards. This could confuse AI agents about which guidelines take precedence.If the intent is for Microsoft Style Guide to serve as the foundation with WSO2-specific standards as refinements or overrides, consider adding explicit guidance about the hierarchy. Otherwise, the instructions should be aligned to reference a single authoritative style guide.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/skills/fix-documentation-issues/SKILL.md around lines 27 - 29, The document mandates the Microsoft Style Guide but conflicts with WSO2-specific authoring standards added elsewhere; update the SKILL.md text (the three bullets that start "ABSOLUTELY MANDATORY:", "MOST IMPORTANT:", and the images rule) to explicitly state the hierarchy and precedence: say that the Microsoft Style Guide is the base/reference standard and that WSO2 Identity Server authoring standards (as defined in .github/copilot-instructions.md) are authoritative overrides/refinements for product-specific terminology, voice, and formatting; also add a short note directing authors to consult .github/copilot-instructions.md for WSO2-specific exceptions and to avoid changing existing content unless instructed.
🧹 Nitpick comments (1)
.github/skills/fix-documentation-issues/SKILL.md (1)
10-10: Consider hyphenating compound modifiers.Standard grammar calls for hyphens in compound modifiers that precede nouns: "version-control-related operations" and "third-party tools". While the wso2/docs-is repository prefers unhyphenated compound adjectives in documentation prose for natural flow, this applies to the documentation content itself. In agent instruction files, following standard grammar rules improves clarity.
✍️ Suggested refinement
-- MOST IMPORTANT: For all version control related operations, rely on the git command line tool and GitHub CLI. **NO THIRD PARTY TOOLS OR MCP SERVERS ARE ALLOWED.** +- MOST IMPORTANT: For all version-control-related operations, rely on the git command line tool and GitHub CLI. **NO THIRD-PARTY TOOLS OR MCP SERVERS ARE ALLOWED.**Based on learnings: "In the wso2/docs-is repository documentation files, prefer unhyphenated compound adjectives for better readability and natural flow" — but this learning applies to documentation prose, not instructional meta-files.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/skills/fix-documentation-issues/SKILL.md at line 10, The sentence "MOST IMPORTANT: For all version control related operations, rely on the git command line tool and GitHub CLI. NO THIRD PARTY TOOLS OR MCP SERVERS ARE ALLOWED." should use hyphenated compound modifiers for clarity in this instruction file: change "version control related operations" to "version-control-related operations" and "THIRD PARTY TOOLS" to "third-party tools" (preserve emphasis/uppercase styling as needed), and ensure "MCP SERVERS" remains clear (e.g., "MCP servers") to match casing conventions in this meta-file.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/skills/fix-documentation-issues/SKILL.md:
- Line 6: The file contains an inline Vale directive "<!-- vale off -->" that
conflicts/redundantly overlaps with the .vale.ini section named
"[**/SKILLS.md]"; remove one of them to avoid ambiguity — either delete the
inline "<!-- vale off -->" from SKILL.md so the .vale.ini rules apply, or remove
the "[**/SKILLS.md]" section from .vale.ini so the inline directive is the sole
control; update whichever location you change and run Vale to verify the
intended rules are applied.
In @.vale.ini:
- Around line 25-29: The .vale.ini section for [**/copilot-instructions.md]
contains an empty BasedOnStyles and dangling Microsoft.* overrides; either
remove the Microsoft overrides entirely to disable Vale checks for
copilot-instructions.md, or set BasedOnStyles = WSO2-IAM and keep the
Microsoft.Headings = NO and Microsoft.GeneralURL = No lines if you intend to
base rules on WSO2-IAM while explicitly disabling those Microsoft rules; update
the BasedOnStyles value and/or remove the Microsoft.* lines in the
[**/copilot-instructions.md] block accordingly.
- Around line 31-35: The override section [**/SKILLS.md] contains an empty
BasedOnStyles which nullifies the Microsoft.* rules; remove the empty
BasedOnStyles key or set it to a valid base style so the Microsoft.Headings and
Microsoft.GeneralURL/Spelling settings take effect — i.e., edit the
[**/SKILLS.md] stanza to either delete the BasedOnStyles line or assign it a
proper style name, and keep or adjust the Microsoft.Headings,
Microsoft.GeneralURL, and Spelling entries accordingly.
---
Outside diff comments:
In @.github/skills/fix-documentation-issues/SKILL.md:
- Around line 27-29: The document mandates the Microsoft Style Guide but
conflicts with WSO2-specific authoring standards added elsewhere; update the
SKILL.md text (the three bullets that start "ABSOLUTELY MANDATORY:", "MOST
IMPORTANT:", and the images rule) to explicitly state the hierarchy and
precedence: say that the Microsoft Style Guide is the base/reference standard
and that WSO2 Identity Server authoring standards (as defined in
.github/copilot-instructions.md) are authoritative overrides/refinements for
product-specific terminology, voice, and formatting; also add a short note
directing authors to consult .github/copilot-instructions.md for WSO2-specific
exceptions and to avoid changing existing content unless instructed.
---
Duplicate comments:
In @.vale.ini:
- Around line 14-15: Remove the stale Microsoft.* override directives from
.vale.ini: delete the entries "Microsoft.Headings = NO" and
"Microsoft.GeneralURL = No" because BasedOnStyles no longer includes Microsoft
and those rule files were removed; update the override block to only reference
existing styles to avoid referencing non-existent rules.
- Around line 21-22: Remove the dead Microsoft.* overrides from .vale.ini by
deleting the entries Microsoft.Headings and Microsoft.GeneralURL (they reference
rules/styles no longer loaded and are duplicates of the overrides on lines
14-15); ensure no other Microsoft.* keys remain and save the cleaned .vale.ini
so the configuration only contains active rule overrides.
---
Nitpick comments:
In @.github/skills/fix-documentation-issues/SKILL.md:
- Line 10: The sentence "MOST IMPORTANT: For all version control related
operations, rely on the git command line tool and GitHub CLI. NO THIRD PARTY
TOOLS OR MCP SERVERS ARE ALLOWED." should use hyphenated compound modifiers for
clarity in this instruction file: change "version control related operations" to
"version-control-related operations" and "THIRD PARTY TOOLS" to "third-party
tools" (preserve emphasis/uppercase styling as needed), and ensure "MCP SERVERS"
remains clear (e.g., "MCP servers") to match casing conventions in this
meta-file.
| description: Guidelines to follow for sending fixes for documentation related GitHub issues | ||
| --- | ||
|
|
||
| <!-- vale off --> |
There was a problem hiding this comment.
Vale directive potentially conflicts with .vale.ini configuration.
This file includes <!-- vale off --> to disable Vale, but .vale.ini lines 31-35 also define a [**/SKILLS.md] section with specific configuration. While the inline directive takes precedence, having both is redundant. Consider removing either the inline directive or the .vale.ini section to avoid confusion about which configuration is active.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/skills/fix-documentation-issues/SKILL.md at line 6, The file
contains an inline Vale directive "<!-- vale off -->" that conflicts/redundantly
overlaps with the .vale.ini section named "[**/SKILLS.md]"; remove one of them
to avoid ambiguity — either delete the inline "<!-- vale off -->" from SKILL.md
so the .vale.ini rules apply, or remove the "[**/SKILLS.md]" section from
.vale.ini so the inline directive is the sole control; update whichever location
you change and run Vale to verify the intended rules are applied.
| [**/copilot-instructions.md] | ||
| BasedOnStyles = | ||
| Microsoft.Headings = NO | ||
| Microsoft.GeneralURL = No | ||
| Spelling = no |
There was a problem hiding this comment.
Dead configuration: Microsoft. overrides with empty BasedOnStyles.*
This section has an empty BasedOnStyles, so the Microsoft rule overrides on lines 27-28 reference non-existent rules. If the intent is to disable all Vale checks for copilot-instructions.md, the Microsoft overrides should be removed. If the intent is to apply WSO2-IAM styles with Microsoft overrides disabled, then add WSO2-IAM to BasedOnStyles and keep the overrides (though this seems inconsistent with the removal of Microsoft from other sections).
💡 If disabling all checks is intended
[**/copilot-instructions.md]
BasedOnStyles =
-Microsoft.Headings = NO
-Microsoft.GeneralURL = No
Spelling = no📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [**/copilot-instructions.md] | |
| BasedOnStyles = | |
| Microsoft.Headings = NO | |
| Microsoft.GeneralURL = No | |
| Spelling = no | |
| [**/copilot-instructions.md] | |
| BasedOnStyles = | |
| Spelling = no |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.vale.ini around lines 25 - 29, The .vale.ini section for
[**/copilot-instructions.md] contains an empty BasedOnStyles and dangling
Microsoft.* overrides; either remove the Microsoft overrides entirely to disable
Vale checks for copilot-instructions.md, or set BasedOnStyles = WSO2-IAM and
keep the Microsoft.Headings = NO and Microsoft.GeneralURL = No lines if you
intend to base rules on WSO2-IAM while explicitly disabling those Microsoft
rules; update the BasedOnStyles value and/or remove the Microsoft.* lines in the
[**/copilot-instructions.md] block accordingly.
| [**/SKILLS.md] | ||
| BasedOnStyles = | ||
| Microsoft.Headings = NO | ||
| Microsoft.GeneralURL = No | ||
| Spelling = no |
There was a problem hiding this comment.
Dead configuration: Microsoft. overrides with empty BasedOnStyles.*
Same issue as the [**/copilot-instructions.md] section: empty BasedOnStyles means these Microsoft overrides have no effect.
💡 Proposed cleanup
[**/SKILLS.md]
BasedOnStyles =
-Microsoft.Headings = NO
-Microsoft.GeneralURL = No
Spelling = no📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [**/SKILLS.md] | |
| BasedOnStyles = | |
| Microsoft.Headings = NO | |
| Microsoft.GeneralURL = No | |
| Spelling = no | |
| [**/SKILLS.md] | |
| BasedOnStyles = | |
| Spelling = no |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.vale.ini around lines 31 - 35, The override section [**/SKILLS.md] contains
an empty BasedOnStyles which nullifies the Microsoft.* rules; remove the empty
BasedOnStyles key or set it to a valid base style so the Microsoft.Headings and
Microsoft.GeneralURL/Spelling settings take effect — i.e., edit the
[**/SKILLS.md] stanza to either delete the BasedOnStyles line or assign it a
proper style name, and keep or adjust the Microsoft.Headings,
Microsoft.GeneralURL, and Spelling entries accordingly.
2 participants
Purpose
$subject
Summary by CodeRabbit
Release Notes