HYPERFLEET-425 - docs: add commit message standard #61
Conversation
Define commit message format and conventions for all HyperFleet repositories based on Conventional Commits specification.
WalkthroughAdds a new documentation file hyperfleet/standards/commit-standard.md that defines the HyperFleet Commit Message Standard. The document prescribes a Conventional Commits–based header (optional org/JIRA prefix), a 72-character line limit, header/body/footer structure, two added commit types (style, perf), a comprehensive table of types with examples, guidance for type selection, rules for breaking changes and multi-ticket footers, and notes on CI enforcement and related resources. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks✅ Passed checks (3 passed)
Comment |
|
Note: The relative links to |
![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: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/standards/commit-standard.md
🧰 Additional context used
🪛 LanguageTool
hyperfleet/standards/commit-standard.md
[grammar] ~75-~75: Use a hyphen to join words.
Context: ...ter exception | | docs | Documentation only changes | Updating README or API do...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/standards/commit-standard.md
43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
132-132: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
144-144: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
hyperfleet/standards/commit-standard.md (2)
71-83: Verify commit types are aligned with PR objectives.The types table includes
style(line 76) andperf(line 78), but the PR objectives list the standard types as: feat, fix, docs, refactor, test, build, ci, chore, revert. Clarify whether these additional types are intentional extensions or should be removed to match the stated standard.
1-164: Comprehensive and well-structured documentation.The document effectively establishes a clear, actionable commit message standard based on Conventional Commits. The structure with overview, detailed format specifications, practical examples, and external references is excellent. Guidelines for type selection and breaking change requirements are appropriately detailed.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
hyperfleet/standards/commit-standard.md (1)
130-140: Clarify the purpose of the Examples section.The examples block shows multiple commit headers in a single code block but lacks context explaining what scenario this represents (e.g., "Sample commit headers showing header-only format with and without JIRA tickets"). The section could benefit from a brief introductory sentence or subsection labels to guide the reader.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/standards/commit-standard.md
🧰 Additional context used
🪛 LanguageTool
hyperfleet/standards/commit-standard.md
[grammar] ~75-~75: Use a hyphen to join words.
Context: ...ter exception | | docs | Documentation only changes | Updating README or API do...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (1)
hyperfleet/standards/commit-standard.md (1)
164-165: Links to referenced standards will be broken until PR #60 merges.These relative links reference sibling documentation files (
makefile-conventions.mdandlinting-standard.md) that are being moved/created by PR #60. Until that PR is merged, these links will be broken. This is expected per the PR description but ensure both PRs are coordinated for timely merge.
ciaranRoche
left a comment
ciaranRoche
left a comment
There was a problem hiding this comment.
It might be worth adding an enforcement guidance in this document, will we have a CI job, or will we be adding it via commit hooks etc.
|
Great point from both @ciaranRoche and @xueli181114! For enforcement, I suggest a phased approach:
I've created a follow-up ticket to implement CI validation: https://issues.redhat.com/browse/HYPERFLEET-432 |
Refs: HYPERFLEET-432
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/standards/commit-standard.md
🧰 Additional context used
🪛 LanguageTool
hyperfleet/standards/commit-standard.md
[grammar] ~82-~82: Use a hyphen to join words.
Context: ...ter exception | | docs | Documentation only changes | Updating README or API do...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (1)
hyperfleet/standards/commit-standard.md (1)
187-188: Relative links will be broken until PR #60 is merged.The references to
makefile-conventions.mdandlinting-standard.md(lines 187–188) assume those files exist at./makefile-conventions.mdand./linting-standard.md. Per the PR objectives, PR #60 moves the standards directory structure, so these links will be broken until that PR merges and is incorporated.Consider adding a temporary note in the document or updating the links once PR #60 is available, to avoid confusing readers navigating the repository in the interim.
| ```text | ||
| HYPERFLEET-567 - feat: rename cluster phase to status | ||
|
|
||
| BREAKING CHANGE: ClusterStatus.phase field renamed to ClusterStatus.status. | ||
| API clients reading cluster status will receive errors on the old field. | ||
| Update all references from .phase to .status in your code. | ||
| ``` |
There was a problem hiding this comment.
Breaking change example violates the stated 72-character line limit.
Lines 154–156 of the breaking change example exceed the 72-character maximum specified in the "Commit Message Format" section (line 70):
- Line 154: 78 characters
- Line 155: 76 characters
Either adjust the example to fit within the limit or clarify whether the limit applies only to commit headers.
🔎 Suggested fix for the breaking change example
HYPERFLEET-567 - feat: rename cluster phase to status
-BREAKING CHANGE: ClusterStatus.phase field renamed to ClusterStatus.status.
-API clients reading cluster status will receive errors on the old field.
-Update all references from .phase to .status in your code.
+BREAKING CHANGE: ClusterStatus.phase field renamed to status.
+Old API clients will error when reading the renamed field.
+Update code: change .phase to .status.🤖 Prompt for AI Agents
hyperfleet/standards/commit-standard.md around lines 151 to 157: the breaking
change example text exceeds the 72-character line limit specified earlier;
either reflow the example so each line is ≤72 characters (wrap the long
sentences into multiple lines preserving wording and markup) or add a clarifying
sentence near the "Commit Message Format" section stating that the 72-character
limit applies only to commit headers and not to body or breaking-change
blocks—pick one approach and apply it consistently to the example and related
guidance.
3 participants
Summary
Add commit message standard document for all HyperFleet repositories based on Conventional Commits specification.
Key Features
HYPERFLEET-XXX - <type>: <subject>BREAKING CHANGE:footer with what/impact/migrationDocument Location
hyperfleet/standards/commit-standard.mdRelated
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.