Skip to content

docs: fix optional arguments shown as required, document defaults and dry-run - #121

Closed
jirkasemmler wants to merge 1 commit into
jirka/readme-safety-fixesfrom
jirka/readme-args-defaults
Closed

docs: fix optional arguments shown as required, document defaults and dry-run#121
jirkasemmler wants to merge 1 commit into
jirka/readme-safety-fixesfrom
jirka/readme-args-defaults

Conversation

@jirkasemmler

Copy link
Copy Markdown
Contributor

Changes:

Second half of the README audit - the presentational findings. Nothing here is a false statement; each one just makes a reader do more work than needed.

  • Optional arguments shown as required. Three usage lines put optional args in <angle brackets>: hostname-suffix in manage:reset-organization-workspace-passwords and manage:set-organization-storage-backend, and hostname-suffix, reason, estimatedEndTime in manage:set-organization-maintenance-mode. Now [<bracketed>].
  • Undocumented defaults. hostname-suffix = keboola.com for both BYODB commands, and connectionUrl = https://connection.keboola.com for storage:lineage-events-export. Both BYODB sections now list arguments and options in the same format the rest of the README uses.
  • Five sections did not mention dry-run even though the code prints DRY RUN without --force: the two BYODB commands above, plus manage:projects-add-feature, manage:projects-remove-feature and manage:organizations-add-feature. Verified in each command before documenting it. Reuses the exact sentence the neighbouring add-feature-to-templates section already had, rather than inventing new phrasing.
  • Fixes Hostname sUffix.

Stacked on #120 - both PRs edit README.md, so this branch is based on that one to avoid a guaranteed conflict. Merge #120 first; the diff shown here against main will then be just this commit. The diff against #120's branch is 29 insertions / 4 deletions.

After both, re-running the audit script reports 0 problems: every registered command has its own section, every default is documented, no optional argument is presented as required, and every command with --force says so.

Docs only, no code touched.


Additional notes

⚠️ Don't forget to release new version after merge

🤖 Generated with Claude Code

… dry-run

Continues the README audit. These are presentation bugs rather than wrong
statements, but each one makes a reader pass an argument they do not need or
miss that a command is safe to try.

Three usage lines showed optional arguments in <angle brackets> as if they were
required: hostname-suffix in reset-organization-workspace-passwords and
set-organization-storage-backend, and hostname-suffix, reason and
estimatedEndTime in set-organization-maintenance-mode. The defaults behind them
were undocumented too, so both BYODB commands now list their arguments and
options the way the rest of the README does.

Five sections did not mention dry-run even though the command prints DRY RUN
without --force: the two BYODB ones above plus projects-add-feature,
projects-remove-feature and organizations-add-feature. The neighbouring
add-feature-to-templates section already carried that sentence, so the same
wording is reused.

Also documents the connectionUrl default for storage:lineage-events-export and
fixes "Hostname sUffix".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@jirkasemmler

Copy link
Copy Markdown
Contributor Author

Superseded by #122 — same commit, rebased onto main.

This PR was auto-closed when #120 was merged with branch deletion: it was stacked on jirka/readme-safety-fixes, so deleting that branch removed its base and GitHub closed it rather than retargeting. A closed PR cannot have its base changed, hence the new one.

@jirkasemmler
jirkasemmler deleted the jirka/readme-args-defaults branch September 8, 2026 08:54
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.

2 participants