HYPERFLEET-385: Define documentation standard and add templates #70
Conversation
WalkthroughAdds a centralized HyperFleet Documentation Standard at hyperfleet/docs/documentation.md and three template files under hyperfleet/docs/templates/: README.md.template, CONTRIBUTING.md.template, and CHANGELOG.md.template. The standard defines repository-wide documentation requirements (README, CONTRIBUTING, CHANGELOG), a docs/ layout with api/, architecture/, and examples/, ADR guidance, OpenAPI/Swagger and Go doc notes, and a templates/ directory for bootstrapping. An initial changelog entry dated 2026-01-08 records the initial version and included templates. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used🪛 LanguageToolhyperfleet/docs/documentation.md[uncategorized] ~113-~113: If this is a compound adjective that modifies the following noun, use a hyphen. (EN_COMPOUND_ADJECTIVE_INTERNAL) 🔇 Additional comments (4)
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: 4
🤖 Fix all issues with AI agents
In @hyperfleet/docs/documentation.md:
- Around line 172-201: Add a top-level "## [Unreleased]" version header before
the existing category sections so the changelog follows Keep a Changelog;
specifically insert a line "## [Unreleased]" immediately above the first "###
Added" (so the file now has "## [Unreleased]" then the "###
Added/Changed/Deprecated/Removed/Fixed/Security" sections) and keep the existing
"## [1.0.0] - YYYY-MM-DD" release entry for historical releases.
- Line 155: Update the incorrect relative link in documentation.md: replace the
path "../architecture/hyperfleet/standards/commit-standard.md" with the correct
"../standards/commit-standard.md" for the sentence "This project follows
[HyperFleet commit standards](...)" so it matches the reference pattern used
elsewhere (lines 227-229) and correctly points to the hyperfleet/standards
directory.
In @hyperfleet/docs/templates/CHANGELOG.md.template:
- Around line 8-28: The template currently lists top-level category headers
(e.g., "### Added", "### Changed") outside any version section; restructure it
to follow Keep a Changelog by creating a top-level "## [Unreleased]" section and
moving the category headings ("### Added", "### Changed", "### Deprecated", "###
Removed", "### Fixed", "### Security") beneath it, and keep the existing "##
[1.0.0] - YYYY-MM-DD" section with its own nested "### Added" entry for the
initial release; remove the orphaned category headers at top level so all
categories are nested under a version header (Unreleased or a specific release).
In @hyperfleet/docs/templates/README.md.template:
- Around line 36-51: The numbered steps in README.md.template skip step 5 (they
go 1,2,3,4,6); update the sequence so the final "Start service" line uses step 5
instead of step 6 (i.e., change "6. Start service" to "5. Start service") so the
list reads 1–5 in order.
🧹 Nitpick comments (1)
hyperfleet/docs/documentation.md (1)
19-29: Add language identifier to code block.The directory structure code block should specify a language identifier for proper rendering and to satisfy markdown linting standards.
🎨 Proposed fix
-``` +```text repository-name/ ├── README.md # Project overview and getting started (REQUIRED)
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
hyperfleet/docs/documentation.mdhyperfleet/docs/templates/CHANGELOG.md.templatehyperfleet/docs/templates/CONTRIBUTING.md.templatehyperfleet/docs/templates/README.md.template
🧰 Additional context used
🪛 LanguageTool
hyperfleet/docs/documentation.md
[uncategorized] ~112-~112: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ories**: API Resources, Authentication, Rate Limiting - Infrastructure repositories: Arch...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/documentation.md
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
hyperfleet/docs/templates/CONTRIBUTING.md.template (1)
1-165: LGTM - Comprehensive and well-structured template.The contributing guide template provides a thorough scaffold covering all essential sections: development setup, repository structure, testing, common tasks, and release process. The placeholder notation is consistent, and the structure aligns well with the documentation standard.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @hyperfleet/docs/documentation.md:
- Line 156: The link target for the "HyperFleet commit standards" reference is
incorrect; update the markdown line that links to the HyperFleet commit
standards so it points to the repository's standards directory (use the shorter
relative path under ../standards for the commit-standard.md file) instead of the
current overly-nested relative path. Ensure the updated link matches the working
references used elsewhere (lines that correctly point to the same
commit-standard.md) so the documentation link resolves.
- Around line 19-29: The fenced code block that shows the directory structure
(the triple-backtick block starting with "repository-name/") is missing a
language specifier; update the opening fence to include a language (for example
use "text" so it reads ```text) and keep the closing triple backticks unchanged
so the block is properly highlighted and markdown-compliant.
🧹 Nitpick comments (1)
hyperfleet/docs/documentation.md (1)
109-116: Minor: Clarify list formatting for consistency.The "Repository-Specific Sections" uses bold text to denote repository types (e.g., "API repositories"). Consider whether "Infrastructure-repositories" at line 113 should follow the same pattern for consistency, or if the current format is intentional.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/docs/documentation.md
🧰 Additional context used
🪛 LanguageTool
hyperfleet/docs/documentation.md
[uncategorized] ~113-~113: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ories**: API Resources, Authentication, Rate Limiting - Infrastructure repositories: Arch...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/documentation.md
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
hyperfleet/docs/documentation.md (2)
1-11: Well-structured documentation standard.The document establishes a clear, comprehensive standard for repository documentation across HyperFleet. The structure is logical, requirements are well-defined, and guidance is actionable. The inclusion of templates, references to industry standards (Keep a Changelog, OpenAPI 3.0), and optional ADR support demonstrates good practices.
243-258: Template files are present and correctly documented.All three template files referenced in the documentation are present in the repository:
templates/README.md.templatetemplates/CONTRIBUTING.md.templatetemplates/CHANGELOG.md.templateNo action needed.
| ### Security | ||
| - Vulnerability fixes | ||
|
|
||
| ## [1.0.0] - YYYY-MM-DD |
There was a problem hiding this comment.
How about adding another [1.0.1] example in same flat level to show how we organize z-stream release
| ### Security | ||
| - Vulnerability fixes | ||
|
|
||
| ## [1.0.0] - YYYY-MM-DD |
There was a problem hiding this comment.
Update the example to show the version number as a link to the GitHub diff. This is especially useful for Z-stream releases to see what small fix was applied."
| - Deprecations and removals | ||
|
|
||
| 2. **What NOT to include:** | ||
| - Internal refactoring that doesn't affect users |
There was a problem hiding this comment.
We need to refine the Internal here. Clarify that for this repo, 'refactoring' only means editorial/layout fixes. If a component boundary or interface changes, it must be logged as it impacts E2E testing
2 participants
Changed
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.