fix(DOC-1675): document --overprovisioned flag and improve rpk redpanda start prose#1618
fix(DOC-1675): document --overprovisioned flag and improve rpk redpanda start prose#1618
Conversation
…da start prose - Add missing --overprovisioned flag to the flags table with a description explaining that it disables thread affinity to allow fairer CPU distribution and must not be used in production environments - Fix several pre-existing prose issues: lowercase 'redpanda' in prose, 'setup' used as a verb, missing comma after introductory clause, future tense 'will disable/enable', 'terser', and weak constructions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughDocumentation updates to the Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc (1)
101-102: Consider linking--overprovisionedto the mode reference for deeper context.Optional docs polish: append an
xrefto therpk redpanda modepage so readers can immediately see the full implications of this flag (for example, dev-mode side effects beyond CPU pinning).✍️ Suggested doc tweak
-|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`. +|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`. For details, see xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc[].Based on learnings, AsciiDoc links with empty brackets are preferred in this repository.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc` around lines 101 - 102, Add an AsciiDoc cross-reference from the --overprovisioned entry to the rpk redpanda mode reference so readers can jump to full mode details: locate the table cell containing the --overprovisioned description and append an xref to the "rpk redpanda mode" page using the repository-preferred empty-bracket syntax; ensure the link text is not added (use the empty brackets style) and that the xref points to the correct page ID/title for the rpk redpanda mode documentation.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc`:
- Around line 101-102: Add an AsciiDoc cross-reference from the
--overprovisioned entry to the rpk redpanda mode reference so readers can jump
to full mode details: locate the table cell containing the --overprovisioned
description and append an xref to the "rpk redpanda mode" page using the
repository-preferred empty-bracket syntax; ensure the link text is not added
(use the empty brackets style) and that the xref points to the correct page
ID/title for the rpk redpanda mode documentation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ff6ed3f0-19d6-4a2d-be58-b253220450ca
📒 Files selected for processing (1)
modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc
|
@kbatuigas — this adds the missing |
…tainer section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Review Summary
The core issue (DOC-1675)
DOC-1675 reports that --overprovisioned is mentioned but not described in the flags table. This PR manually adds it and improves prose throughout the page.
How rpk reference docs work
The flags table in this file (the == Usage and == Flags sections) is auto-generated by our doc-tools rpk automation:
gen-rpk-ascii.pystarts Redpanda in Docker, runsrpk <command> -hrecursively, and generates.adocfiles- Output goes to
autogenerated/<tag>/rpk/*.adoc - The generator deletes and recreates each file entirely — there is no override mechanism for rpk docs (unlike
property-overrides.jsonfor properties) - The generated files are then reviewed and copied into
modules/reference/pages/rpk/
Impact on this PR
The file has two zones with different behavior:
| Zone | What's there | Overwritten on regen? |
|---|---|---|
| Manual prose (lines 1–43: title, "Set up a mode" section) | Hand-written | No |
Flags table (lines 45–154: == Usage + == Flags) |
From rpk --help |
Yes — completely |
The --overprovisioned flag already exists in rpk --help, so regenerating rpk docs with npx doc-tools generate rpk-docs --tag <version> would automatically add it to the flags table — with the description from the binary.
The prose improvements to existing flag descriptions (--check, --tune, --timeout, --config, --config-opt) will also be reverted to whatever rpk --help outputs on the next regeneration.
Recommendation
Rather than manually editing the auto-generated flags table, the right approach for DOC-1675 is to regenerate the rpk docs from a Redpanda version that includes the --overprovisioned flag. This will:
- Add the missing
--overprovisionedrow automatically - Keep the flags table in sync with the actual CLI help text
- Avoid the manual edits being silently overwritten later
The manual prose improvements (lines 8–43 — heading fix, intro rewrite, capitalization) are safe and won't be overwritten. Those changes are good and could be kept in a smaller PR if desired.
Style notes (minor)
The prose changes are well-written. Two small suggestions if they're kept:
"Set automatically by --mode dev-container"→"Set automatically when using --mode dev-container"for more natural phrasing"After Redpanda starts, modify the cluster properties by running:"— consider"After Redpanda starts, you can modify cluster properties by running:"since reference pages describe capabilities, not instructions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The --overprovisioned flag is a Seastar passthrough, not an rpk flag, so it does not appear in rpk help output and will be dropped on any future regen. Document it via xref to rpk-redpanda-mode.adoc, which already has a full explanation (including the Seastar reference). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Reword lead-in to direct imperative (no "To [verb], run:")
- Remove "you can" weak construction
- Fix "--timeout" description awkward phrasing ("tune processes")
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4 participants
Summary
--overprovisionedflag to therpk redpanda startflags table with a description explaining that it disables thread affinity (CPU pinning) to allow fairer CPU distribution and must not be used in production environmentsredpandain prose,setupused as a verb, missing comma after introductory clause, future tense (will disable/enable), comparativeterser, and weak constructions (It's possible to,When present will)Test plan
--overprovisionedflag appears in the flags table with correct description🤖 Generated with Claude Code