HYPERFLEET-1186 - docs: restructure documentation #194
HYPERFLEET-1186 - docs: restructure documentation #194openshift-merge-bot[bot] merged 2 commits into
Conversation
|
Warning Review limit reached
More reviews will be available in 26 minutes and 26 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Central YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughRoot Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 11✅ Passed checks (11 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Risk Score: 2 —
|
| Signal | Detail | Points |
|---|---|---|
| PR size | 1150 lines (>500) | +2 |
| Sensitive paths | none | +0 |
Computed by hyperfleet-risk-scorer
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/adapter-authoring-guide.md (1)
1549-1549:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAvoid plaintext credentials in documentation examples (CWE-798).
Line 1549 shows an inline password in the broker URL example. Even for documentation templates, demonstrate secret-reference patterns instead to avoid normalizing credential exposure.
Recommend revising to show Kubernetes Secret mounting or environment variable substitution:
broker: type: rabbitmq rabbitmq: url: "amqp://$(RABBITMQ_USER):$(RABBITMQ_PASS)`@rabbitmq`:5672/"Or reference the pattern from the deployment guide for Secret-backed credentials.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adapter-authoring-guide.md` at line 1549, The RabbitMQ URL example in the broker configuration contains hardcoded credentials (the inline password in the "amqp://user:pass@rabbitmq:5672/" URL), which exposes security risks. Replace the hardcoded credentials with environment variable references like RABBITMQ_USER and RABBITMQ_PASS using variable substitution syntax, or alternatively reference the existing Secret-backed credentials pattern documented in the deployment guide to demonstrate secure credential handling. This ensures the documentation examples promote best practices for secret management instead of normalizing credential exposure.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/adapter-authoring-guide.md`:
- Line 1549: The RabbitMQ URL example in the broker configuration contains
hardcoded credentials (the inline password in the
"amqp://user:pass@rabbitmq:5672/" URL), which exposes security risks. Replace
the hardcoded credentials with environment variable references like
RABBITMQ_USER and RABBITMQ_PASS using variable substitution syntax, or
alternatively reference the existing Secret-backed credentials pattern
documented in the deployment guide to demonstrate secure credential handling.
This ensures the documentation examples promote best practices for secret
management instead of normalizing credential exposure.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Central YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 5bbf0ef7-a3e5-4a7e-afaa-51d97e2ab2d2
📒 Files selected for processing (11)
README.mdcharts/README.mdcharts/README.md.gotmpldocs/adapter-authoring-guide.mddocs/configuration.mddocs/conventions/cel.mddocs/conventions/logging.mddocs/deployment.mddocs/development.mddocs/metrics.mddocs/runbook.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift-hyperfleet/architecture(manual)openshift-hyperfleet/hyperfleet-api(manual)openshift-hyperfleet/hyperfleet-sentinel(manual)openshift-hyperfleet/hyperfleet-adapter(manual)openshift-hyperfleet/hyperfleet-broker(manual)
| | `broker.rabbitmq.queue` | Queue name (required) | `""` | | ||
| | `broker.rabbitmq.exchange` | Exchange name (required) | `""` | | ||
| | `broker.rabbitmq.exchangeType` | Exchange type | `topic` | | ||
| | `broker.rabbitmq.routingKey` | Routing key (required) | `""` | |
There was a problem hiding this comment.
As discussed, this is not really requried
… development guides
Slim down README.md to a navigation hub and split deployment/development
content into focused standalone guides so operators and developers can
find what they need without cross-referencing multiple documents.
- Add docs/deployment.md: Helm deployment guide covering the three-tier
config mechanism (dedicated values, env list, adapterConfig.yaml blob),
adapter/task/broker config sourcing options, tracing, auto-set env vars,
and complete deployment examples (RabbitMQ + Maestro/Pub/Sub)
- Add docs/development.md: developer setup, build, test, and dry-run guide
- Slim README.md from ~530 to ~90 lines with audience-separated doc links
(Operators / Adapter Authors / Developers / Architecture)
- Add tracing (OpenTelemetry) section to docs/configuration.md and
tracing troubleshooting section to docs/runbook.md
- Add deployment guide link to charts/README.md.gotmpl and regenerate
charts/README.md
- Add CHANGELOG.md unreleased section covering v0.2.0..HEAD changes
- Update example values and adapter-config for RabbitMQ defaults
sherine-k
force-pushed
the
HYPERFLEET-1186
branch
from
319a052 to
6def399
Compare
| - **Docker or Podman** must be running (both supported) | ||
| - The Makefile automatically detects and configures your container runtime | ||
| - **Podman users**: Corporate proxy settings are auto-detected from Podman machine. Define and export the environment variable : | ||
| ``` |
There was a problem hiding this comment.
Tip
nit — non-blocking suggestion
Category: Pattern
This code fence is missing a language identifier (MD040). All other code blocks in this file use bash or json. Adding bash here keeps it consistent and enables syntax highlighting.
| ``` | |
| ```bash |
| @@ -0,0 +1,183 @@ | |||
| # Setup | |||
There was a problem hiding this comment.
Tip
nit — non-blocking suggestion
Category: Pattern
All other docs in this directory start with a document title and audience statement (deployment.md, adapter-authoring-guide.md, metrics.md, runbook.md, etc.). This file jumps straight to # Setup. Consider adding a title and audience line for consistency:
| # Setup | |
| # Development Guide | |
| > **Audience:** Developers building and testing the adapter locally. | |
| ## Setup |
This also fixes the heading hierarchy — the current # Setup, # Verification, # Make Targets etc. would become ##-level sections under the document title.
| | `OTEL_TRACES_SAMPLER` | Sampler type (`always_on`, `always_off`, `traceidratio`, `parentbased_*`) | `parentbased_traceidratio` | | ||
| | `OTEL_TRACES_SAMPLER_ARG` | Sampling ratio (0.0–1.0) | `1.0` | | ||
|
|
||
| When no `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces are written to stdout for local development. |
There was a problem hiding this comment.
Tip
nit — non-blocking suggestion
Category: Improvement
Trailing whitespace at end of line. Some editors and linters flag this.
| When no `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces are written to stdout for local development. | |
| When no `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces are written to stdout for local development. |
|
Tip nit — non-blocking suggestion Category: Pattern The PR description mentions two changes that aren't in the diff:
If these were intentionally dropped, updating the description avoids confusion for reviewers. |
|
/test helm-test |
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: rafabene 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 34ceb40
into
openshift-hyperfleet:main
3 participants
Summary
Slim down README.md to a navigation hub and split deployment/development content into focused standalone guides so operators and developers can find what they need without cross-referencing multiple documents.
Add docs/deployment.md: Helm deployment guide covering the three-tier config mechanism (dedicated values, env list, adapterConfig.yaml blob), adapter/task/broker config sourcing options, tracing, auto-set env vars, and complete deployment examples (RabbitMQ + Maestro/Pub/Sub)
Add docs/development.md: developer setup, build, test, and dry-run guide
Slim README.md from ~530 to ~90 lines with audience-separated doc links (Operators / Adapter Authors / Developers / Architecture)
Add tracing (OpenTelemetry) section to docs/configuration.md and tracing troubleshooting section to docs/runbook.md
Add deployment guide link to charts/README.md.gotmpl and regenerate charts/README.md
HYPERFLEET-1186
Test Plan
make test-allpassesmake lintpassesmake test-helm(if applicable)