HYPERFLEET-761 - docs: align with documentation standards#30
Conversation
Add CONTRIBUTING.md, CHANGELOG.md, and CLAUDE.md to meet HyperFleet documentation standards and optimize for AI agent workflows. - CONTRIBUTING.md: Development setup, repo structure, testing, commit standards, and release process - CHANGELOG.md: Keep a Changelog format with semantic versioning - CLAUDE.md: AI agent context under 200 lines with build commands, validation checklist, code conventions, and boundaries - README.md: Add Architecture repo link and Contributing section Addresses requirements from HYPERFLEET-761 for standardizing documentation across HyperFleet repositories. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
WalkthroughAdds documentation and guidance files to the HyperFleet API specification repository: a top-level CHANGELOG.md (Keep a Changelog format with Unreleased, v1.0.2, v1.0.0 entries), CLAUDE.md (TypeSpec→OpenAPI generation workflow, provider aliasing, build/validation, conventions, and release steps), CONTRIBUTING.md (prereqs, setup, build/validation, repository layout, common tasks, commit/PR guidance), and updates README.md to add contribution links and format external URLs. No source code or exported/public API entities were changed. 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. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
rh-amarin
changed the title
![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 `@CHANGELOG.md`:
- Line 28: Change the release note sentence on Line 28 from “Updated OWNERS file
to not block approval by bot” to a clearer phrasing such as “Updated OWNERS file
to prevent bot approval from being blocked.” Locate the text in CHANGELOG.md and
replace the awkward construction with the suggested wording (or equivalent clear
passive-voice-free phrasing) so the intent reads smoothly.
In `@CLAUDE.md`:
- Line 40: Two fenced code blocks in CLAUDE.md (one containing the text
"Provider-specific → `models-{provider}/`" and the other the similar
provider-path example) are missing language info strings; update each
triple-backtick fence to include a language identifier such as "text" or "bash"
(e.g., change ``` to ```text) so the markdown lint rule MD040 is satisfied and
the examples render/lint correctly.
🪄 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: 8b62fd26-cca1-46bd-8f73-491a1963cad4
📒 Files selected for processing (4)
CHANGELOG.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
| ### Changed | ||
| - Standardized TypeSpec schema definitions with enums and validation enhancements | ||
| - Refactored to support oapi-codegen compatibility | ||
| - Updated OWNERS file to not block approval by bot |
There was a problem hiding this comment.
Improve wording clarity on Line 28.
“Updated OWNERS file to not block approval by bot” reads awkwardly in release notes. Prefer a clearer phrasing like “Updated OWNERS file to prevent bot approval from being blocked.”
Suggested edit
-- Updated OWNERS file to not block approval by bot
+- Updated OWNERS file to prevent bot approval from being blocked📝 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.
| - Updated OWNERS file to not block approval by bot | |
| - Updated OWNERS file to prevent bot approval from being blocked |
🧰 Tools
🪛 LanguageTool
[style] ~28-~28: Consider changing the order of words to improve your wording.
Context: ...gen compatibility - Updated OWNERS file to not block approval by bot ### Fixed - Rele...
(TO_NOT_VB)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CHANGELOG.md` at line 28, Change the release note sentence on Line 28 from
“Updated OWNERS file to not block approval by bot” to a clearer phrasing such as
“Updated OWNERS file to prevent bot approval from being blocked.” Locate the
text in CHANGELOG.md and replace the awkward construction with the suggested
wording (or equivalent clear passive-voice-free phrasing) so the intent reads
smoothly.
|
|
||
| **When adding new models:** | ||
| - Shared models → `models/` | ||
| - Provider-specific → `models-{provider}/` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
Markdown lint flags fenced blocks without a language at these lines. Add explicit info strings (for example, text or bash) to keep docs lint-clean.
Suggested fix pattern
-```
+```text
...
(Apply similarly to the other affected fenced block.)
</details>
Also applies to: 199-199
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>
[warning] 40-40: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @CLAUDE.md at line 40, Two fenced code blocks in CLAUDE.md (one containing
the text "Provider-specific → models-{provider}/" and the other the similar
provider-path example) are missing language info strings; update each
triple-backtick fence to include a language identifier such as "text" or "bash"
(e.g., change totext) so the markdown lint rule MD040 is satisfied and
the examples render/lint correctly.
</details>
<!-- fingerprinting:phantom:triton:hawk:a8eb15fd-9578-47e7-89aa-3de217432631 -->
<!-- This is an auto-generated comment by CodeRabbit -->
ciaranRoche
left a comment
ciaranRoche
left a comment
There was a problem hiding this comment.
Two nits inline, but otherwise looks good to me
|
|
||
| ## Dependencies | ||
|
|
||
| All TypeSpec libraries use version `^1.6.0` for consistency: |
There was a problem hiding this comment.
Is this correct? 🤔 REST and versioning are not on this version
There was a problem hiding this comment.
These are transitive dependencies for the important ones like compiler
| - Separate public and internal status endpoints | ||
| - Interactive API documentation | ||
|
|
||
| ### Architecture |
There was a problem hiding this comment.
Is this standard ChangeLog category?
rh-amarin
force-pushed
the
docs/hyperfleet-761-documentation-standards
branch
from
8d75ca6 to
73e6051
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (1)
CHANGELOG.md (1)
32-32:⚠️ Potential issue | 🟡 MinorImprove phrasing on release note entry.
“Updated OWNERS file to not block approval by bot” is awkward and can be clearer.
Suggested edit
-- Updated OWNERS file to not block approval by bot +- Updated OWNERS file to prevent bot approval from being blockedAs per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CHANGELOG.md` at line 32, The release note entry wording is awkward; replace the line "Updated OWNERS file to not block approval by bot" with a clearer, concise phrasing such as "Updated OWNERS file to allow bot approvals" (or "Updated OWNERS file to prevent bots from blocking approvals" if that better matches intent); update the exact changelog entry text accordingly to improve clarity and readability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CHANGELOG.md`:
- Line 32: The release note entry wording is awkward; replace the line "Updated
OWNERS file to not block approval by bot" with a clearer, concise phrasing such
as "Updated OWNERS file to allow bot approvals" (or "Updated OWNERS file to
prevent bots from blocking approvals" if that better matches intent); update the
exact changelog entry text accordingly to improve clarity and readability.
|
|
||
| ## Commit Standards | ||
|
|
||
| We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: |
There was a problem hiding this comment.
There was a problem hiding this comment.
Yes, that is better
|
|
||
| For broader HyperFleet architecture context and documentation standards, see the [HyperFleet Architecture Repository](https://github.com/openshift-hyperfleet/architecture). | ||
|
|
||
| ## Adding a New Provider |
There was a problem hiding this comment.
We could remove this part from README as it is in CONTRIBUTING
| ln -sf aliases-gcp.tsp aliases.tsp | ||
| ``` | ||
|
|
||
| The VS Code extension uses whichever provider `aliases.tsp` points to. |
There was a problem hiding this comment.
I remember there’s a way to render the OpenAPI spec directly in VS Code, similar to a localhost Swagger UI, but I’ve forgotten how to set it up.
It would be great to include this, as it’s quite useful.
rh-amarin
force-pushed
the
docs/hyperfleet-761-documentation-standards
branch
from
73e6051 to
e25d3fd
Compare
Add v1.0.0 and v1.0.2 release entries with key changes extracted from GitHub release notes. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
rh-amarin
force-pushed
the
docs/hyperfleet-761-documentation-standards
branch
from
e25d3fd to
5643c75
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
CHANGELOG.md (1)
32-32:⚠️ Potential issue | 🟡 MinorRephrase this release note for clarity.
Current wording is awkward; use clearer phrasing.
Suggested edit
-- Updated OWNERS file to not block approval by bot +- Updated OWNERS file to prevent bot approval from being blocked🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CHANGELOG.md` at line 32, Reword the release note "Updated OWNERS file to not block approval by bot" in CHANGELOG.md to clearer phrasing; replace it with a concise, active-voice sentence such as "Updated OWNERS to allow bot approvals" or "Adjusted OWNERS file so bot approvals are not blocked" (choose one) so the intent is unambiguous—locate the exact string in CHANGELOG.md and update it accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 44-67: Two fenced code blocks in CONTRIBUTING.md are missing
language identifiers; add a language tag (use "text") to the block containing
the repository tree starting with "hyperfleet-api-spec/" and to the block
containing the changelog lines starting with "feat: add NodePool autoscaling
fields..." so both open fences become "```text"; ensure both closing fences
remain unchanged.
- Around line 23-27: Replace the global install instruction for TypeSpec (the
line suggesting `npm install -g `@typespec/compiler``) with guidance to use the
repository's pinned toolchain: instruct contributors to run `npm install` and
the existing build scripts (e.g., `npm run build:core`, `npm run build:gcp`) or
use `npx `@typespec/compiler`` to run the locally installed `@typespec/compiler`
referenced in package.json; ensure the text mentions the repo pins (npm@11.6.2
and `@typespec/compiler`@^1.6.0) so readers understand why a local install is
required.
---
Duplicate comments:
In `@CHANGELOG.md`:
- Line 32: Reword the release note "Updated OWNERS file to not block approval by
bot" in CHANGELOG.md to clearer phrasing; replace it with a concise,
active-voice sentence such as "Updated OWNERS to allow bot approvals" or
"Adjusted OWNERS file so bot approvals are not blocked" (choose one) so the
intent is unambiguous—locate the exact string in CHANGELOG.md and update it
accordingly.
🪄 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: 15778b99-fbe7-4ca5-b65f-97c0e5552c45
📒 Files selected for processing (2)
CHANGELOG.mdCONTRIBUTING.md
| 2. Install TypeSpec compiler globally: | ||
|
|
||
| ```bash | ||
| npm install -g @typespec/compiler | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether the repo already pins TypeSpec locally and exposes script-based builds.
# Expected: `@typespec/compiler` is present in package.json deps/devDeps and build scripts exist.
fd -HI '^package.json$' | xargs -I{} sh -c '
echo "== {} =="
rg -n "\"packageManager\"|\"@typespec/compiler\"|\"build:core\"|\"build:gcp\"|\"build:all\"" "{}"
'Repository: openshift-hyperfleet/hyperfleet-api-spec
Length of output: 494
🏁 Script executed:
#!/bin/bash
# Read CONTRIBUTING.md around lines 23-27 and check for MD040 warnings
fd -HI '^CONTRIBUTING.md$' | head -1 | xargs -I{} sh -c '
echo "=== Lines 20-35 (context around 23-27) ==="
sed -n "20,35p" "{}" | cat -n
echo ""
echo "=== Lines 40-70 (context around line 44 mentioned for MD040) ==="
sed -n "40,70p" "{}" | cat -n
echo ""
echo "=== Total lines in file ==="
wc -l "{}"
'Repository: openshift-hyperfleet/hyperfleet-api-spec
Length of output: 2020
Avoid global TypeSpec installs; use local pinned toolchain via npm install and build scripts.
Lines 23-27 recommend npm install -g @typespec/compiler, which conflicts with the repo's pinned versions in `package.json` (npm@11.6.2 and `@typespec/compiler`@^1.6.0). Contributors using the global install will diverge from the project's locked toolchain, causing inconsistent schema output. Instead, direct users to run `npm install` followed by the provided build scripts (`npm run build:core`, `npm run build:gcp`, etc.) or use `npx `@typespec/compiler.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CONTRIBUTING.md` around lines 23 - 27, Replace the global install instruction
for TypeSpec (the line suggesting `npm install -g `@typespec/compiler``) with
guidance to use the repository's pinned toolchain: instruct contributors to run
`npm install` and the existing build scripts (e.g., `npm run build:core`, `npm
run build:gcp`) or use `npx `@typespec/compiler`` to run the locally installed
`@typespec/compiler` referenced in package.json; ensure the text mentions the repo
pins (npm@11.6.2 and `@typespec/compiler`@^1.6.0) so readers understand why a
local install is required.
There was a problem hiding this comment.
♻️ Duplicate comments (2)
CONTRIBUTING.md (2)
23-33:⚠️ Potential issue | 🟠 MajorUse the repo-pinned TypeSpec toolchain instead of global install
Line 23 conflicts with Line 29: global
@typespec/compilercan drift from the project’s pinned setup and produce inconsistent outputs across contributors. Prefer local install (npm install) and invoking via scripts ornpx@typespec/compiler``.Suggested doc fix
-2. Install TypeSpec compiler globally: - - ```bash - npm install -g `@typespec/compiler` - ``` - -3. Install project dependencies: +2. Install project dependencies (recommended: use repo-pinned toolchain): ```bash npm install ``` + +3. Run TypeSpec using project scripts or local binary: + + ```bash + npm run build:core + npm run build:gcp + # or + npx `@typespec/compiler` --help + ```As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` around lines 23 - 33, Replace the global install instruction `npm install -g `@typespec/compiler`` with guidance to use the repo-pinned toolchain: consolidate step 2 to run `npm install` (install project dependencies) and add a new step 3 that instructs contributors to run TypeSpec via project scripts or the local binary (e.g., `npm run build:core` / `npm run build:gcp` or `npx `@typespec/compiler``) so everyone uses the pinned version instead of a global `@typespec/compiler`.
44-67:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks to satisfy markdownlint
Line 44 and Line 206 open unlabeled fenced blocks, which triggers MD040 and can break lint-gated docs checks.
Suggested doc fix
-``` +```text hyperfleet-api-spec/ ├── main.tsp # Main TypeSpec entry point ... └── schemas/ # Generated OpenAPI outputs ├── core/ └── gcp/@@
-+text
feat: add NodePool autoscaling fields to GCP spec
fix: correct required fields in ClusterStatus model
docs: update README with new provider examples
refactor: consolidate common status fieldsAlso applies to: 206-211
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` around lines 44 - 67, Update the two unlabeled fenced code blocks in CONTRIBUTING.md by adding a language identifier (e.g., ```text) to satisfy markdownlint MD040: locate the first fenced block that starts with the hyperfleet-api-spec/ directory tree and the second fenced block that contains the short commit messages (feat: add NodePool..., fix: correct..., etc.), and change the opening fences to include a language token such as "text" so both blocks become ```text.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CONTRIBUTING.md`:
- Around line 23-33: Replace the global install instruction `npm install -g
`@typespec/compiler`` with guidance to use the repo-pinned toolchain: consolidate
step 2 to run `npm install` (install project dependencies) and add a new step 3
that instructs contributors to run TypeSpec via project scripts or the local
binary (e.g., `npm run build:core` / `npm run build:gcp` or `npx
`@typespec/compiler``) so everyone uses the pinned version instead of a global
`@typespec/compiler`.
- Around line 44-67: Update the two unlabeled fenced code blocks in
CONTRIBUTING.md by adding a language identifier (e.g., ```text) to satisfy
markdownlint MD040: locate the first fenced block that starts with the
hyperfleet-api-spec/ directory tree and the second fenced block that contains
the short commit messages (feat: add NodePool..., fix: correct..., etc.), and
change the opening fences to include a language token such as "text" so both
blocks become ```text.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8d0245eb-e0cb-46a7-adca-34d4c9376429
📒 Files selected for processing (3)
CHANGELOG.mdCONTRIBUTING.mdREADME.md
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: yasun1 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-merge-bot
Bot
merged commit 6b9148e
into
openshift-hyperfleet:main
3 participants
https://redhat.atlassian.net/browse/HYPERFLEET-761
Added required files from our standard for documentation
Summary by CodeRabbit