create a standard-document-template.md #69
Conversation
WalkthroughA new Markdown template file was added to Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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
🧹 Nitpick comments (1)
hyperfleet/standards/standard-document-template.md (1)
3-8: Instruction comments are helpful but somewhat verbose.The instructional HTML comments throughout the template (e.g., lines 3–8, 16–20, 34–37) provide valuable guidance for first-time users. However, they are quite detailed. Consider condensing them for brevity while retaining essential information, especially since authors will remove them before finalizing documents.
Also applies to: 16-20, 34-37
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
hyperfleet/standards/directory-structure.mdhyperfleet/standards/standard-document-template.md
🔇 Additional comments (3)
hyperfleet/standards/standard-document-template.md (3)
1-287: Comprehensive template structure provides excellent documentation framework.The template is well-organized with clear sections for Goals, Non-Goals, Applicability, Component-Specific Guidelines, Configuration, Examples (with DO/DON'T patterns), Enforcement, Action Items, and References. The inclusion of RFC 2119 guidance (MUST/SHOULD/MAY) and precedence rules for configuration options demonstrates thoughtful design. The Component-Specific Guidelines sections appropriately acknowledge that API, Sentinel, and Adapters may have different requirements.
67-78: Reference Implementation section thoughtfully handles planned libraries.The inclusion of a note about planned shared libraries (e.g., "planned - see HYPERFLEET-XXX") acknowledges that standards may reference components under development, which is pragmatic for the HyperFleet context.
241-263: Action Items format with metadata enables effective ticket tracking.The inclusion of Priority (High/Medium/Low) and Size (S/M/L/XL) metadata in the Action Items section provides sufficient structure to convert items into JIRA tickets with minimal additional context.
| ## Table of Contents | ||
|
|
||
| <!-- | ||
| INSTRUCTIONS: Include a Table of Contents for documents with 5+ sections. | ||
| Update section numbers and names to match your actual content. | ||
| For shorter documents, this section can be omitted. | ||
| --> | ||
|
|
||
| 1. [Overview](#overview) | ||
| 2. [Section Name](#section-name) | ||
| 3. [Examples](#examples) | ||
| 4. [Action Items](#action-items) | ||
| 5. [References](#references) | ||
|
|
||
| --- |
There was a problem hiding this comment.
Table of Contents doesn't list all major sections.
Lines 22–26 list only 5 sections, but the document contains 8 major sections. The ToC is missing Configuration (line 128), Component-Specific Guidelines (line 146), and Enforcement (line 219).
📋 Proposed fix to update the Table of Contents
1. [Overview](#overview)
2. [Section Name](#section-name)
+3. [Configuration](#configuration)
+4. [Component-Specific Guidelines](#component-specific-guidelines)
-3. [Examples](#examples)
-4. [Action Items](#action-items)
-5. [References](#references)
+5. [Examples](#examples)
+6. [Enforcement](#enforcement)
+7. [Action Items](#action-items)
+8. [References](#references)📝 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.
| ## Table of Contents | |
| <!-- | |
| INSTRUCTIONS: Include a Table of Contents for documents with 5+ sections. | |
| Update section numbers and names to match your actual content. | |
| For shorter documents, this section can be omitted. | |
| --> | |
| 1. [Overview](#overview) | |
| 2. [Section Name](#section-name) | |
| 3. [Examples](#examples) | |
| 4. [Action Items](#action-items) | |
| 5. [References](#references) | |
| --- | |
| ## Table of Contents | |
| <!-- | |
| INSTRUCTIONS: Include a Table of Contents for documents with 5+ sections. | |
| Update section numbers and names to match your actual content. | |
| For shorter documents, this section can be omitted. | |
| --> | |
| 1. [Overview](#overview) | |
| 2. [Section Name](#section-name) | |
| 3. [Configuration](#configuration) | |
| 4. [Component-Specific Guidelines](#component-specific-guidelines) | |
| 5. [Examples](#examples) | |
| 6. [Enforcement](#enforcement) | |
| 7. [Action Items](#action-items) | |
| 8. [References](#references) | |
| --- |
|
|
||
| This standard applies to: | ||
|
|
||
| - All HyperFleet service repositories |
There was a problem hiding this comment.
In #68 @rafabene is proposing this classification of repository types, which may make more sense to live in the directory-structure.md document, or in the https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/docs/repository-creation-guidelines.md
Supported repository types:
| Type | Value | Required Targets |
|---|---|---|
| Service | service |
help, build, test, lint, clean |
| Helm-chart | helm-chart |
help, helm-lint, helm-template, helm-test |
| Infrastructure | infrastructure |
help, lint, clean |
| Documentation | documentation |
Makefile not required |
| ## Configuration | ||
|
|
||
| <!-- | ||
| INSTRUCTIONS: If the standard involves configurable options, | ||
| document them in a table with flags, environment variables, and defaults. | ||
| Remove this section if not applicable. | ||
| --> | ||
|
|
||
| All components MUST support configuration via **command-line flags** and **environment variables**. | ||
|
|
||
| | Option | Flag | Environment Variable | Default | Description | | ||
| |--------|------|---------------------|---------|-------------| | ||
| | Option Name | `--option-name` | `OPTION_NAME` | `default` | What this option controls | | ||
|
|
||
| **Precedence** (highest to lowest): flags → environment variables → config file → defaults |
There was a problem hiding this comment.
#66 is trying to standardize the configuration, should this section detailing the format go there?
That document says that configuration for each project should go in a docs/config.md file
| ## Action Items | ||
|
|
||
| <!-- | ||
| INSTRUCTIONS: List outstanding work and implementation items related to this standard. | ||
| Each item should have enough detail to be converted into a JIRA ticket. | ||
| Remove items as they are completed or converted to tickets. | ||
|
|
||
| Priority: High (blocking other work) | Medium (important) | Low (nice to have) | ||
| Size: S (< 1 day) | M (1-3 days) | L (3-5 days) | XL (needs breakdown) | ||
| --> | ||
|
|
||
| - **Action item name** | ||
| - Description: What needs to be done and why | ||
| - Acceptance Criteria: How to verify the work is complete | ||
| - Priority: High | Medium | Low | ||
| - Size: S | M | L | XL | ||
|
|
||
| - **Another action item** | ||
| - Description: What needs to be done and why | ||
| - Acceptance Criteria: How to verify the work is complete | ||
| - Priority: High | Medium | Low | ||
| - Size: S | M | L | XL |
There was a problem hiding this comment.
Won't this information be repeated here and in a ticket?
My concern is having it duplicated and then drift, so we don't know which is the source of truth
2 participants
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.