HYPERFLEET-761 - Add documentation standards: CHANGELOG.md and CLAUDE.md#92
HYPERFLEET-761 - Add documentation standards: CHANGELOG.md and CLAUDE.md#92rh-amarin wants to merge 1 commit intoopenshift-hyperfleet:mainfrom
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds three documentation updates: a new CHANGELOG.md using "Keep a Changelog" with releases 0.2.0 (2026-03-30), 0.1.1 (2026-03-10) and 0.1.0 (2026-02-19) detailing Added/Changed/Fixed items (including a Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 1-223: The CLAUDE.md exceeds the target length; trim it to under
200 lines by condensing or removing non-essential examples and verbose lists:
shorten the "Quick Reference" and "Essential Commands" sections (remove long
code blocks or combine similar commands), collapse verbose examples in "Code
Conventions" (keep one short logging and one short error example), compress
"Project Structure" to a single-line summary or remove less-critical folders,
and move extended "Common Tasks" or "Links" entries to a separate docs page;
target keeping headers like "Quick Reference", "Validation Checklist", and
one-line summaries for "Project Structure" and "Code Conventions" to preserve
context while reducing length.
- Line 7: Update the Go version string in CLAUDE.md to match the project's
go.mod requirement: replace "Go 1.24.6+" with "Go 1.25.0" (or "Go 1.25.0+" if
you prefer a plus qualifier) so the documentation aligns with the go.mod
declared minimum Go version.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 50c03284-2bbd-4cb0-a0ec-2110c39230a5
📒 Files selected for processing (2)
CHANGELOG.mdCLAUDE.md
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
CLAUDE.md (1)
1-223:⚠️ Potential issue | 🟡 Minor
CLAUDE.mdstill exceeds the stated<200 linesconstraint.This remains at 223 lines, so the PR objective for AI-agent size optimization is still unmet.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 1 - 223, The CLAUDE.md file is 223 lines which exceeds the <200 lines constraint; reduce its length to <=200 lines by trimming or collapsing verbose sections. Edit CLAUDE.md to shorten overly long sections (e.g., “Project Structure”, “Code Conventions”, “Boundaries - Do NOT Do This”, “Common Tasks”, and “Release Process”) by removing redundant bullet points, combining similar items, and converting long examples into a single short pointer (keep the Quick Reference, essential commands, and the most critical conventions). Ensure headings and examples still convey necessary guidance but the total file length is at most 200 lines and update any line-count dependent metadata if present.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 50-75: The fenced code block in CLAUDE.md containing the project
tree (the triple-backtick block that starts with "pkg/ # Exported
packages...") lacks a language specifier causing MD040; update that opening
fence from "```" to "```text" so the tree-style block is explicitly marked as
plain text (no other changes to the block content).
---
Duplicate comments:
In `@CLAUDE.md`:
- Around line 1-223: The CLAUDE.md file is 223 lines which exceeds the <200
lines constraint; reduce its length to <=200 lines by trimming or collapsing
verbose sections. Edit CLAUDE.md to shorten overly long sections (e.g., “Project
Structure”, “Code Conventions”, “Boundaries - Do NOT Do This”, “Common Tasks”,
and “Release Process”) by removing redundant bullet points, combining similar
items, and converting long examples into a single short pointer (keep the Quick
Reference, essential commands, and the most critical conventions). Ensure
headings and examples still convey necessary guidance but the total file length
is at most 200 lines and update any line-count dependent metadata if present.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ``` | ||
| pkg/ # Exported packages (can be imported by other projects) | ||
| ├── constants/ # Shared constants (annotations, labels) | ||
| ├── errors/ # Error handling utilities with codes | ||
| ├── health/ # Health and metrics HTTP servers | ||
| ├── logger/ # Structured logging with context | ||
| ├── otel/ # OpenTelemetry tracing | ||
| ├── utils/ # General utilities | ||
| └── version/ # Version info | ||
|
|
||
| internal/ # Internal packages (not importable) | ||
| ├── config_loader/ # YAML config loading + validation | ||
| ├── criteria/ # Precondition and CEL evaluation | ||
| ├── executor/ # Event execution pipeline (phases) | ||
| ├── hyperfleet_api/ # HyperFleet API client | ||
| ├── k8s_client/ # Kubernetes client wrapper | ||
| ├── maestro_client/ # Maestro/OCM ManifestWork client | ||
| ├── manifest/ # Manifest generation and rendering | ||
| └── transport_client/ # Unified apply interface | ||
|
|
||
| cmd/adapter/ # Main entry point | ||
| test/integration/ # Integration tests | ||
| charts/ # Helm chart | ||
| configs/ # Config templates and examples | ||
| scripts/ # Build scripts | ||
| ``` |
There was a problem hiding this comment.
Add a language to the fenced project-structure block.
The code fence starting at Line 50 has no language specifier (MD040). Use text for this tree-style block.
Proposed fix
-```
+```text
pkg/ # Exported packages (can be imported by other projects)
├── constants/ # Shared constants (annotations, labels)
├── errors/ # Error handling utilities with codes
@@
scripts/ # Build scripts</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **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.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 50-50: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 50 - 75, The fenced code block in CLAUDE.md
containing the project tree (the triple-backtick block that starts with "pkg/
# Exported packages...") lacks a language specifier causing MD040; update that
opening fence from "```" to "```text" so the tree-style block is explicitly
marked as plain text (no other changes to the block content).
rh-amarin
force-pushed
the
HYPERFLEET-761-docs-update
branch
from
895fdcb to
4dd34a0
Compare
pnguyen44
left a comment
pnguyen44
left a comment
There was a problem hiding this comment.
I left a few comments. In addition, 223 lines exceed the HYPERFLEET-761 requirement of <200 lines. Consider trimming 23+ lines by condensing examples or moving "Common Tasks" to a separate doc.
CLAUDE.md
Outdated
| 4. Document in adapter authoring guide | ||
|
|
||
| ### Adding Metrics | ||
| 1. Define metric in `pkg/health/metrics.go` |
There was a problem hiding this comment.
Define metric in pkg/health/metrics.go" is misleading. pkg/health/metrics.go is the Prometheus HTTP server wiring. Adapter-specific metrics (the hyperfleet_adapter_* counters/histograms) are defined in pkg/metrics/recorder.go, which is where new metrics should go.
rh-amarin
force-pushed
the
HYPERFLEET-761-docs-update
branch
from
4dd34a0 to
ea137a8
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (3)
CLAUDE.md (3)
53-53:⚠️ Potential issue | 🟡 MinorAdd a language identifier to the project-structure fence (MD040).
Line 53 opens a fenced block without a language; use
textto satisfy markdownlint and improve tooling support.Proposed fix
-``` +```text pkg/ # Exported packages (can be imported by other projects) ... -``` +```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 53, The fenced code block that begins with the project structure listing (the block showing "pkg/ # Exported packages (can be imported by other projects)" etc.) is missing a language identifier; update the opening fence from "```" to "```text" so the markdown lint rule MD040 is satisfied and tooling correctly treats the block as plain text.
1-259:⚠️ Potential issue | 🟠 MajorTrim
CLAUDE.mdto meet the stated<200 linesstandard.This file is currently 259 lines, so it misses the documented constraint for AI-agent consumption. Please condense sections (especially examples and task walkthroughs) to get under 200 lines while keeping core commands/boundaries.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 1 - 259, Summary: CLAUDE.md exceeds the <200 lines limit; trim verbose examples and duplicate content and condense sections. Fix: in CLAUDE.md keep the core headers (Quick Reference, Essential Commands, Validation Checklist, Project Structure, Code Conventions, Boundaries, Testing Patterns, Common Tasks, Release Process) but remove the long example blocks and lengthy walkthroughs (e.g., full code snippets under "Logging", "Table-Driven Tests", and "Integration Test Setup"), collapse Project Structure tree to a one-line list of major dirs, shorten Common Tasks steps to 2–3 bullets each, delete the duplicate_comment marker, and ensure the file is under 200 lines while preserving the essential commands and rules for agent use. Use the file name CLAUDE.md and the section headings above to locate and edit the content.
238-241:⚠️ Potential issue | 🟠 MajorFix incorrect metrics extension point in “Common Tasks”.
Line 240 points contributors to
pkg/health/metrics.go, but adapter-specific metrics are defined inpkg/metrics/recorder.go. Keeping this as-is will send changes to the wrong module.Proposed fix
-1. Define metric in `pkg/health/metrics.go` +1. Define metric in `pkg/metrics/recorder.go`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 238 - 241, Update the "Adding Metrics" Common Tasks entry to point contributors to the adapter-specific metrics implementation in pkg/metrics/recorder.go (not pkg/health/metrics.go); change the instruction text to reference the recorder implementation and its public API (e.g., the Recorder type and its Register/Record methods such as NewRecorder or RegisterAdapterMetrics) so contributors add/modify metrics in recorder.go where adapter metrics are implemented.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CLAUDE.md`:
- Line 53: The fenced code block that begins with the project structure listing
(the block showing "pkg/ # Exported packages (can be imported by
other projects)" etc.) is missing a language identifier; update the opening
fence from "```" to "```text" so the markdown lint rule MD040 is satisfied and
tooling correctly treats the block as plain text.
- Around line 1-259: Summary: CLAUDE.md exceeds the <200 lines limit; trim
verbose examples and duplicate content and condense sections. Fix: in CLAUDE.md
keep the core headers (Quick Reference, Essential Commands, Validation
Checklist, Project Structure, Code Conventions, Boundaries, Testing Patterns,
Common Tasks, Release Process) but remove the long example blocks and lengthy
walkthroughs (e.g., full code snippets under "Logging", "Table-Driven Tests",
and "Integration Test Setup"), collapse Project Structure tree to a one-line
list of major dirs, shorten Common Tasks steps to 2–3 bullets each, delete the
duplicate_comment marker, and ensure the file is under 200 lines while
preserving the essential commands and rules for agent use. Use the file name
CLAUDE.md and the section headings above to locate and edit the content.
- Around line 238-241: Update the "Adding Metrics" Common Tasks entry to point
contributors to the adapter-specific metrics implementation in
pkg/metrics/recorder.go (not pkg/health/metrics.go); change the instruction text
to reference the recorder implementation and its public API (e.g., the Recorder
type and its Register/Record methods such as NewRecorder or
RegisterAdapterMetrics) so contributors add/modify metrics in recorder.go where
adapter metrics are implemented.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8a9ca768-c3e3-413f-b86a-bcc6571cd0af
📒 Files selected for processing (2)
CHANGELOG.mdCLAUDE.md
✅ Files skipped from review due to trivial changes (1)
- CHANGELOG.md
|
/retest |
|
/retest |
|
Do you know why the ticket says "Do not auto-generate -- research (ETH Zurich, Feb 2026) shows auto-generated context files degrade agent performance by ~3% and increase inference costs by 20%+. These must be authored by developers familiar with each repo" for CLAUDE.md? |
CHANGELOG.md
Outdated
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
Category: Bug
Tag v0.2.0 was created on 2026-03-30 — after this PR was opened but before merge. The CHANGELOG currently jumps from [Unreleased] to [0.1.1], missing the v0.2.0 release entirely.
Please add a ## [0.2.0] section with the changes from that release, and update the comparison links at the bottom:
[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-adapter/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/openshift-hyperfleet/hyperfleet-adapter/compare/v0.1.1...v0.2.0
CLAUDE.md
Outdated
|
|
||
| // Add structured fields via context or logger chaining | ||
| ctx = logger.WithLogField(ctx, "cluster_id", clusterID) | ||
| log := log.With("resource", name).With("error", err) |
There was a problem hiding this comment.
Category: Inconsistency
The logging example uses logger.Info, logger.Error, and logger.WithLogField above, but this line switches to log.With(...). This is inconsistent — should be logger.With(...) or the variable name should match whatever the actual adapter API uses.
// Current (inconsistent)
log := log.With("resource", name).With("error", err)
// Should match the rest of the example
log := logger.With("resource", name).With("error", err)
rh-amarin
force-pushed
the
HYPERFLEET-761-docs-update
branch
from
ea137a8 to
84d523c
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
CLAUDE.md (2)
53-53:⚠️ Potential issue | 🟡 MinorAdd a language to the project-structure fenced block.
This still trips MD040 and keeps docs lint noisy.
Proposed fix
-``` +```text pkg/ # Exported packages (can be imported by other projects) ... scripts/ # Build scripts</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@CLAUDE.mdat line 53, The fenced code block showing the project-structure
(the block containing "pkg/ # Exported packages... scripts/Build scripts") is missing a language tag and triggers MD040; update the
opening fence from
totext so the block becomes a ```text fenced block to
satisfy the linter and reduce noise.</details> --- `1-263`: _⚠️ Potential issue_ | _🟡 Minor_ **File length still exceeds the stated “under 200 lines” target.** Current size is 263 lines, which weakens the “quick AI context” objective in this PR. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 1 - 263, CLAUDE.md is 263 lines, exceeding the 200-line target; trim and condense to meet the limit by removing or relocating verbose examples and repeated lists: shorten the "Essential Commands" by keeping only the most-used commands, compress "Project Structure" to a one-line summary or move full tree to a separate docs file, collapse long "Code Conventions" and "Boundaries" sections into bullet summaries, and remove duplicated testing examples (or replace full code blocks with a single short snippet reference); look for large fenced code blocks (e.g., the build/test examples and table-driven test sample) and either delete them or replace with a single-line pointer to docs to bring the file under 200 lines. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@CLAUDE.md:
- Line 53: The fenced code block showing the project-structure (the block
containing "pkg/ # Exported packages... scripts/ # Build
scripts") is missing a language tag and triggers MD040; update the opening fence
fromtotext so the block becomes a ```text fenced block to satisfy the
linter and reduce noise.- Around line 1-263: CLAUDE.md is 263 lines, exceeding the 200-line target; trim
and condense to meet the limit by removing or relocating verbose examples and
repeated lists: shorten the "Essential Commands" by keeping only the most-used
commands, compress "Project Structure" to a one-line summary or move full tree
to a separate docs file, collapse long "Code Conventions" and "Boundaries"
sections into bullet summaries, and remove duplicated testing examples (or
replace full code blocks with a single short snippet reference); look for large
fenced code blocks (e.g., the build/test examples and table-driven test sample)
and either delete them or replace with a single-line pointer to docs to bring
the file under 200 lines.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `39bd89e9-309d-458b-87a2-7689b23d6d9f` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ea137a8ddc101a5b80ce1291e5e81581ecdee9ef and 84d523c9c94c6270fc3d0bfd1add9241e1a5205f. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `CHANGELOG.md` * `CLAUDE.md` * `CONTRIBUTING.md` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * CONTRIBUTING.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
rh-amarin
force-pushed
the
HYPERFLEET-761-docs-update
branch
from
84d523c to
9e4cbd3
Compare
4 participants
Summary
Adds required documentation files to meet architecture standards and optimize for AI agent workflows:
CHANGELOG.md - Follows Keep a Changelog format with Semantic Versioning
CLAUDE.md - AI agent optimization context (under 200 lines)
Context
Part of HYPERFLEET-761 to standardize documentation across all HyperFleet core components. The repository already has comprehensive README.md and CONTRIBUTING.md, so this PR adds the two missing required files.
Verification
Version tags used from upstream repository (openshift-hyperfleet/hyperfleet-adapter):
Related Issues
Checklist
🤖 Generated with Claude Code
Summary by CodeRabbit