[Chore] Revise the CLI flags introduced in 0.12.0
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Refactor
- Clarity
- Clearly specified
- Activity status
- Active
- Domain
- cli, documentation
Research direction
This is a tracking parent; its concrete flag decisions must be recorded in the issue body, and each rename, merge, or removal becomes a separate leaf issue. Begin with the named packages under pkg/cmdsetup, banyand, and bydbctl/internal/cmd, then compare their flag registrations with the two flag reference pages and docs/operation/upgrade.md. Done means the review decisions and executable checks are defined for every flag; implementation is not assigned to this parent.
Written by the indexing model from the issue text.
Description
Summary
0.12.0 shipped a batch of new command-line flags. They went into the release without a single review pass over their names, types, defaults, per-role coverage, and documentation. This issue marks that review as outstanding work: revise the flags introduced in 0.12.0 before the 0.12.0 milestone is considered settled.
This is a tracking parent, not an implementation contract. It owns the completion criteria below. The review pass it asks for decides the concrete changes; every rename, merge, or removal then becomes its own executable leaf issue. Do not queue this issue for automated implementation.
Boundary
The CLI flag contract of the shipped binaries:
banyand standalone,banyand data,banyand liaison— the flags each role accepts, their types, defaults, and help text.bydbctl data export— the flags the export command accepts, their types, defaults, and exit codes.
What a caller may rely on: a flag name, its type, its default, and the wording of its help text. What stays free to change without an issue: the implementation behind a flag, and the feature the flag configures.
Flags in scope
The surface added in this release, to be confirmed against the release diff when the review pass starts:
Server (banyand):
--bydbql-plan-cache-size,--bydbql-plan-cache-max-bytes,--bydbql-plan-max-compiles,--bydbql-plan-max-in-flight--stream-export-snapshot-path,--measure-export-snapshot-path,--trace-export-snapshot-path,--property-export-snapshot-path
Client (bydbctl data export):
--dry-run,--output-format/-o,--strict-coverage,--selector,--parallelism,--nodes,--plan
Requirements
- R1. Every flag introduced in 0.12.0 has one recorded decision — keep, rename, merge, or remove — written in this issue body (edit the body; do not leave it in a comment), together with the reason.
- R2. A retained flag's name follows the conventions of the flags around it:
kebab-case,<subject>-<qualifier>shape, no abbreviation the surrounding CLI does not already use, and no name whose meaning shifts between roles. - R3. One knob is not spelled as several near-duplicate flags unless the issue body says why the split is required. The four
--<catalog>-export-snapshot-pathflags are the case in point. - R4. A retained flag has one documented default, equal to the code default, and a type that rejects an invalid value at parse time with a usage error — a value that means "unbounded" or "automatic" is expressed so that
0,abc, and-1are each rejected rather than silently falling back to a default. - R5. A retained flag is documented in
docs/operation/configuration.md(server) ordocs/interacting/bydbctl/bydbctl.md(client) with the same name, default, unit, and wording as--helpprints. - R6. A flag is registered in every role where the feature it configures runs, and
banyand <role> --helplists it in each of those roles. - R7. A flag that is renamed or removed after having shipped in a released version is recorded in
docs/operation/upgrade.mdwith the old name, the new name, and the behaviour change.
Acceptance criteria
- Every requirement above is checked by something that can be run, and the check fails before the corresponding leaf merges and passes after it.
- The final flag names and defaults of
banyand standalone --help,banyand data --help,banyand liaison --help, andbydbctl data export --helpagree withdocs/operation/configuration.mdanddocs/interacting/bydbctl/bydbctl.md. - End to end: a node started with the revised flags answers
bydbctl data export --dry-run --nodes <addr>and renders its report; the same command with an invalid flag value exits with the usage exit code and the message the issue names. - Per role: for each role the flag belongs to, the flag is accepted by that role's binary and rejected by a role it does not belong to.
- Compatibility: any renamed or removed flag that shipped in a released version appears in
docs/operation/upgrade.md.
Scope
- Packages:
pkg/cmdsetup,banyand/liaison/grpc,banyand/stream,banyand/measure,banyand/trace,banyand/property,bydbctl/internal/cmd. - Docs:
docs/operation/configuration.md,docs/interacting/bydbctl/bydbctl.md,docs/operation/upgrade.md. - Out of scope: the behaviour of the features the flags configure (the export session protocol, the measure QL plan cache) beyond what the flag contract itself states; flags that earlier releases already shipped; any new feature.
Size audit
- Classification: tracking parent
- Boundary: the CLI flag contract of the
banyandstandalone/data/liaison binaries and ofbydbctl data export— names, types, defaults, and the documentation stating them. - Production activation:
banyand <role> --help,bydbctl data export --help, and the two flag reference pages. - RED test: a flag-contract test asserting each documented flag is registered on the role's flag set with the documented default; it does not exist today, and each leaf adds the assertion that fails before it.
- End to end:
bydbctl data export --dry-runagainst a running node, and the rejection of an invalid flag value. - Format/lifecycle scope: none — no persisted bytes and no wire format change; the flag contract is a CLI surface.
- Fixtures and oracle: none; the expected values are the flag names and defaults this issue states.
- Focused suites:
make test-ci PKG=./pkg/cmdsetup ./bydbctl/internal/cmd. - Dependencies present on main: yes — the 0.12.0 flags are registered in
pkg/cmdsetup,banyand/liaison/grpc,banyand/{stream,measure,trace,property}, andbydbctl/internal/cmd. - Decision: tracking parent. The review pass names the concrete changes; each rename, merge, or removal becomes its own executable leaf, ordered by dependency.
- Dominant language
- Java
- Stars
- 25k
- Forks
- 6.6k
- Avg merge
- 12h 1m
- Merged PRs (30d)
- 43
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from apache/skywalking
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
apache/skywalking#14239 ·
Maintainers usually reply within 1 day
-
AI Assistant database enhancement
Difficulty 5/5 Over a week Newbie friendliness 24/100
apache/skywalking#14237 ·
Maintainers usually reply within 1 day
-
database enhancement
Difficulty 5/5 Over a week Newbie friendliness 25/100
apache/skywalking#14236 ·
Maintainers usually reply within 1 day
-
AI Assistant database enhancement
Difficulty 5/5 Over a week Newbie friendliness 25/100
apache/skywalking#14235 ·
Maintainers usually reply within 1 day
-
database enhancement
Difficulty 5/5 Over a week Newbie friendliness 30/100
apache/skywalking#14234 ·
Maintainers usually reply within 1 day
All issues in apache/skywalking
Similar issues
-
Re-executed query with IN condition on an index column returns deleted rows (stale IndexCursor)Possibly taken @dbusche claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
h2database/h2database#4580 ·
Maintainers usually reply within 1 day
-
vips-drift
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Stirling-Tools/JPDFium#300 ·
Maintainers usually reply within 1 day
-
hermes-queue
Difficulty 1/5 1-3 hours Newbie friendliness 85/100
chrisalunlloyd2-sudo/mindpalace#403 ·
Maintainers usually reply within 1 day
-
Guidelines: document how to build a use case against a local, unpublished Flow/browserless-test changePossibly taken @totally-not-ai claimed this today. Open
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
vaadin/use-cases#452 · 1 comment ·
Maintainers usually reply within 1 day
-
area/storage area/storage/sql
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Apicurio/apicurio-registry#11159 ·
Maintainers usually reply within 1 day