Skip to content

Clarify local server lifecycle help - #561

Open
sdairs wants to merge 1 commit into
stack/476-fix-start-help-quotesfrom
stack/478-lifecycle-help
Open

Clarify local server lifecycle help#561
sdairs wants to merge 1 commit into
stack/476-fix-start-help-quotesfrom
stack/478-lifecycle-help

Conversation

@sdairs

@sdairs sdairs commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • document exact-current-directory lifecycle scope and current stop/remove omission rules
  • add the canonical named workflow, generated-name retention, and project cleanup guidance
  • contrast installed-version removal with named server-data removal in CLI help and README
  • pin rendered lifecycle help and README removal guidance with exact tests

Tests

  • cargo test -p clickhousectl local::cli::tests::server_
  • cargo test -p clickhousectl local::cli::tests::readme_contrasts_version_and_server_removal
  • cargo test -p clickhousectl
  • cargo fmt --all --check
  • cargo clippy -p clickhousectl --all-targets -- -D warnings

Closes #478

@sdairs

sdairs commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator Author

Carry-over review from PR #520 (old PR for #478). This PR is substantively stronger than #520: stop-selection wording fixed to match the actual code (mod.rs:~896-927), scope sentence consistently worded on every subcommand, removal contrast present in CLI help as well as README, and exact-block assert_eq! pinning instead of #520's substring contains(). All six acceptance criteria met. But it re-adds content sdairs explicitly trimmed on #520. Required:

  1. Reconcile with sdairs' two trim comments on Clarify local server lifecycle help #520 (both re-violated here). On Clarify local server lifecycle help #520, sdairs left two pending review comments, then self-addressed them in commit c764b48 ("Trim local lifecycle help"):

    • Comment 1 (cli.rs): "no need to explain obvious commands that adds nothing over the command descriptor". The trim removed the top-level sentence restating stop-all's descriptor. This PR re-adds that class of content in three places: cli.rs:~313-314 ("For project cleanup, use clickhousectl local server stop-all."), cli.rs:~450 ("Use clickhousectl local server stop-all when the intent is project cleanup."), and README.md:~293. Mitigation: issue Clarify local server lifecycle help: CWD scope, omitted-name behavior, and agent workflow #478 criterion 4 explicitly requires "Help recommends server stop-all when the intent is project cleanup", so the guidance is mandated. A reviewer applying comment 1's standard could still flag the wording as restating the descriptor — either trim to the minimal mandated form or state in the PR description that the earlier trim is being consciously relaxed to satisfy the acceptance criterion.
    • Comment 2 (README.md): "this is a readme, not agent help. this does not need to be added here". The trim removed the generated-name operational reminder from the README. This PR re-adds it nearly verbatim at README.md:~300: "Retain the returned generated name for later stop and remove commands, or pass a name positionally for a stable identity." The CLI help already carries this (cli.rs:~347). Delete the README retain-clause (or justify the reversal explicitly).
  2. Note: the scope sentence is now duplicated verbatim 6 times (group + start/list/stop/stop-all/remove). Any wording change breaks 6 places — acceptable for agent-facing help, but be aware.

  3. CI note: local postgres edge cases fails here; docs-only diff, so this is inherited from the stack base (Validate local Postgres start options #547 script drift). Confirm resolved after that lands and the stack rebases.

Supersede/close #520 when this merges to avoid duplicate "Closes #478".

@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 2a1b601 to c917d4e Compare August 26, 2026 18:58
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from c917d4e to 9355c3d Compare August 26, 2026 19:01
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 3 times, most recently from fbe3d48 to e092ce6 Compare August 26, 2026 19:10
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from e092ce6 to 99ef1c2 Compare August 26, 2026 19:12
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 99ef1c2 to 5a67b3d Compare August 26, 2026 19:20
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 5a67b3d to ade0543 Compare August 26, 2026 19:24
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from ade0543 to 3c09690 Compare August 26, 2026 19:28
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 3c09690 to 94e5a6e Compare August 26, 2026 19:31
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 94e5a6e to 7bdd691 Compare August 26, 2026 19:34
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 7bdd691 to 0bc7268 Compare August 26, 2026 19:36
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 2 times, most recently from 1ceb29d to 4c18155 Compare August 26, 2026 20:30
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 2 times, most recently from 0b3334e to d27f42b Compare August 26, 2026 20:38
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from d27f42b to 8a679fc Compare August 26, 2026 20:41
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 2 times, most recently from 4cb1afa to f02353d Compare August 26, 2026 20:49
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from f02353d to 6a4a01a Compare August 26, 2026 20:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify local server lifecycle help: CWD scope, omitted-name behavior, and agent workflow

1 participant