docs: add CodeRabbit review prompts for documentation #1294
Conversation
Mounil2005
force-pushed
the
feature/coderabbit-docs-prompt
branch
from
ecd8c6c to
32e10f1
Compare
📝 WalkthroughWalkthroughAdds multiple path-specific documentation-review instruction blocks to Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Pre-merge checks✅ Passed checks (5 passed)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro 📒 Files selected for processing (2)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (2)
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: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
.coderabbit.yaml
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (1)
.coderabbit.yaml (1)
171-313: Excellent documentation review structure that aligns well with PR objectives.The three-tier approach (general docs, SDK users, SDK developers) provides comprehensive yet focused guidance:
- Clear differentiation: Each block appropriately targets its audience with relevant priorities
- Principle-driven: Emphasizes correctness, clarity, and usefulness without mandating large restructures
- Actionable: Provides concrete checkpoints rather than vague guidance
- Balanced: The AVOID sections appropriately discourage nitpicking and scope creep
The emphasis on verifying code snippets, checking command accuracy, and validating links addresses the core quality concerns. The explicit handling of mixed-audience pages and training progression is particularly valuable.
Based on learnings, this approach successfully implements the flexible, principle-driven documentation review guidance requested in issue #1236.
Mounil2005
force-pushed
the
feature/coderabbit-docs-prompt
branch
from
32e10f1 to
8dcb557
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
.coderabbit.yaml (1)
171-221: Formatting inconsistency with existing instruction blocks.The existing instruction blocks (examples, unit tests, integration tests) use bold markdown formatting with colons for headers (e.g.,
**Priority 1 - Correctness**:,**PHILOSOPHY**:), while these new documentation blocks use plain text without bold or colons.This was flagged in a previous review. Aligning the formatting would improve consistency across all path instructions.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
.coderabbit.yaml
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (2)
.coderabbit.yaml (2)
222-267: SDK users guidance looks well-structured.The instructions appropriately emphasize copy-pasteable examples, explicit prerequisites, and zero-assumption documentation for SDK users. The focus on "time-to-first-success" aligns well with user-facing documentation goals.
One minor note: Line 240 references "Hedera background" while the project is "Hiero Python SDK." If you want strict naming consistency throughout, consider updating to "Hiero/Hedera" or just "Hedera network" to clarify the relationship.
268-313: SDK developers guidance is comprehensive and well-targeted.The instructions appropriately cover:
- Contribution workflow accuracy (DCO, GPG, CI, branching)
- Training module progression with explicit next steps
- Alignment with codebase conventions and patterns
- Preference for follow-up issues over blocking large restructures
The guidance for
training/specifically addressing module independence and progressive learning flow (Priority 4) is a good addition.
|
Some ideas: - path: "docs/sdk_developers/**"
instructions: |
These docs are for SDK developers and contributors.
FOCUS ON
- Step-by-step instructions that can be followed end-to-end
- Clear prerequisites, assumptions, and setup steps
- Training material that builds understanding progressively
CHECK THAT
- Instructions are explicit, ordered, and complete
- File paths, scripts, workflows, and tooling are accurate
- Each section explains what the reader should do next
AVOID
- Assuming prior knowledge of the codebase
- Nit picking at valuable documentation additions, LGTM is preferred- path: "docs/sdk_users/**"
instructions: |
These docs are for SDK users who want to understand how to use the SDK.
FOCUS ON
- High-level explanation of what the SDK can do and when to use it
- Clear guidance on configuration, concepts, and choices
- Direct links to working examples for copy-paste or execution
CHECK THAT
- Concrete actions are delegated to examples where possible
- Links to examples are easy to find, clearly labeled and correct
AVOID
- Large runnable code blocks, refer to examples- path: "docs/**"
instructions: |
Docs should help readers quickly understand:
- what this page is for
- who it is for and is it for me
- if it is for them, it should teach them the information they need quickly and accurately
- where to go next to solve their problem
CHECK THAT
- The page states its purpose and audience near the top
- It points to the relevant next step (example, guide, training, or reference)
- Information is easy to scan (clear headings, short sections) |
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
.coderabbit.yaml (1)
171-256: Consider consolidating shared principles to reduce repetition.Per earlier feedback, there's opportunity to reduce the prompt length by extracting common PHILOSOPHY and AVOID principles to the base
docs/**block. Currently at ~85 lines; consolidation could reduce to ~60-65 lines.Potential consolidation approach:
- Move shared philosophy (incremental improvements, concise feedback, reader success focus) to the
docs/**block- Move common avoidances (no lint feedback, no large restructures) to the base block
- Keep only audience-specific guidance in
sdk_users/**andsdk_developers/**blocksThat said, the current self-contained structure has clear maintainability benefits—each block is independently understandable. This is a design trade-off rather than a defect.
📝 Example consolidation
Move to
docs/**block:SHARED PHILOSOPHY - Treat docs as work-in-progress: optimize for correctness and clarity. - Keep feedback concise, action-oriented, and focused on reader success. - Prefer follow-up issues for large gaps over blocking PRs. SHARED AVOID - Avoid lint-style feedback on Markdown formatting. - Avoid large-scale restructures unless current structure blocks understanding.Then trim redundant sections from
sdk_users/**andsdk_developers/**blocks.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
.coderabbit.yamlCHANGELOG.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (1)
CHANGELOG.md (1)
124-124: LGTM!The changelog entry accurately describes the documentation review prompts added to
.coderabbit.yamland follows the established format.
Mounil2005
force-pushed
the
feature/coderabbit-docs-prompt
branch
from
6e87b34 to
7acd554
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
CHANGELOG.md (1)
1-1: Remove the BOM (Byte Order Mark) character from the file header.The file begins with a UTF-8 BOM character that can cause issues with certain parsers and tools.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
.coderabbit.yamlCHANGELOG.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (1)
CHANGELOG.md (1)
125-125: LGTM!The changelog entry accurately describes the addition of CodeRabbit documentation review prompts and properly references issue #1236.
Mounil2005
force-pushed
the
feature/coderabbit-docs-prompt
branch
from
7acd554 to
c872870
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
CHANGELOG.md (1)
1-1: BOM character issue previously flagged.This line still contains the UTF-8 BOM character that was flagged in a previous review. Please address the earlier comment to remove it.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
.coderabbit.yamlCHANGELOG.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (1)
CHANGELOG.md (1)
127-127: LGTM! Changelog entry is clear and accurate.The entry accurately describes the documentation review prompts added in this PR, follows project conventions, and links to the correct issue.
exploreriii
left a comment
exploreriii
left a comment
There was a problem hiding this comment.
Very good, last tidy please!
|
Hi, this is MergeConflictBot. Please resolve these conflicts locally and push the changes. To assist you, please read: Thank you for contributing! |
…sdk_developers - General docs guidance with correctness, clarity, completeness, consistency, and navigation priorities - SDK users guidance focused on runnable examples, step-by-step clarity, and zero assumptions - SDK developers guidance emphasizing workflow accuracy, edge cases, and training progression - Edge case checks: external link versioning, deprecated patterns, audience signposts, platform gotchas, and standalone training modules - Audience alignment and explicit next steps for mixed-audience pages and training Resolves hiero-ledger#1236 Signed-off-by: Mounil <[email protected]>
Signed-off-by: Mounil <[email protected]>
Mounil2005
force-pushed
the
feature/coderabbit-docs-prompt
branch
from
c872870 to
23cf578
Compare
Signed-off-by: Mounil <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #1294 +/- ##
=======================================
Coverage 91.80% 91.80%
=======================================
Files 139 139
Lines 8484 8484
=======================================
Hits 7789 7789
Misses 695 695 🚀 New features to boost your workflow:
|
|
Thanks again @Mounil2005 let's see how this goes! |
2 participants
Description:
Related issue(s):
Fixes #1236
Notes for reviewer:
The prompts are designed to treat documentation as work-in-progress, preferring incremental improvements over large restructures, and keeping feedback concise and action-oriented.
Checklist