Skip to content

[vtctldclient] Update CLI docs for usages, flags, and aliases#10502

Merged
ajm188 merged 17 commits intovitessio:mainfrom
planetscale:andrew/vtctldclient/docsdocsdocs
Jun 14, 2022
Merged

[vtctldclient] Update CLI docs for usages, flags, and aliases#10502
ajm188 merged 17 commits intovitessio:mainfrom
planetscale:andrew/vtctldclient/docsdocsdocs

Conversation

@ajm188
Copy link
Copy Markdown
Contributor

@ajm188 ajm188 commented Jun 14, 2022

Description

This is a final pass/cleanup before 14.0, as part of vitessio/website#1054. I'll regenerate the website docs after addressing any feedback on this PR and backporting to release-14.0.

Some things in particular to call out:

  1. I added command aliases for PRS/ERS so users can also specify EmergencyFailoverShard, etc, if they wish.
  2. The Short usage for CreateKeyspace still referenced the deprecated ShardingColumn* options, so I removed them from the example to further discourage users from setting them.

Related Issue(s)

Checklist

  • "Backport me!" label has been added if this change should be backported
  • Tests were added or are not required
  • Documentation was added or is not required

Deployment Notes

Andrew Mason added 15 commits June 14, 2022 09:40
Update docs for backup commands
40e7025 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for cell commands
97f993e 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for keyspace commands
d187d28 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for legacy-shim command
7b5ff2f 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs, add aliases for reparent commands
5429bf5 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for root command
44ee60c 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for routing rule commands
fea683b 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for schema commands
558b6a3 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for serving graph commands
5ad85d4 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for shard commands
a4ff909 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for tablet commands
24de86a 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for vschema commands
8f7ba02 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Update docs for workflow commands
bbe90ff 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Remove references to deprecated flags
092433f 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
fixup! Update docs for keyspace commands
6044b31 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
@ajm188 ajm188 added this to the v14.0 milestone Jun 14, 2022
@ajm188 ajm188 requested a review from deepthi June 14, 2022 13:45
@ajm188 ajm188 requested review from doeg and notfelineit as code owners June 14, 2022 13:45
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jun 14, 2022

Review Checklist

Hello reviewers! 👋 Please follow this checklist when reviewing this Pull Request.

General

  • Ensure that the Pull Request has the correct release notes label. release notes none should only be used for PRs that are so trivial that they need not be included.
  • If a new flag is being introduced, review whether it is really needed. The flag names should be clear and intuitive (as far as possible), and the flag's help should be descriptive.
  • If a workflow is added or modified, each items in Jobs should be named in order to mark it as required. If the workflow should be required, the GitHub Admin should be notified.

Bug fixes

  • There should be at least one unit or end-to-end test.
  • The Pull Request description should either include a link to an issue that describes the bug OR an actual description of the bug and how to reproduce, along with a description of the fix.

Non-trivial changes

  • There should be some code comments as to why things are implemented the way they are.

New/Existing features

  • Should be documented, either by modifying the existing documentation or creating new documentation.
  • New features should have a link to a feature request issue or an RFC that documents the use cases, corner cases and test cases.

Backward compatibility

  • Protobuf changes should be wire-compatible.
  • Changes to _vt tables and RPCs need to be backward compatible.
  • vtctl command output order should be stable and awk-able.

@ajm188 ajm188 mentioned this pull request Jun 14, 2022
Merged
deepthi
deepthi approved these changes Jun 14, 2022
View reviewed changes
Copy link
Copy Markdown
Collaborator

@deepthi deepthi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added command aliases for PRS/ERS so users can also specify EmergencyFailoverShard, etc, if they wish.

This is too consequential a change to get in without further discussion. Let's leave it out of this PR.

The Short usage for CreateKeyspace still referenced the deprecated ShardingColumn* options, so I removed them from the example to further discourage users from setting them.

Good catch 👍

The rest LGTM

Andrew Mason added 2 commits June 14, 2022 14:11
Remove reparent command aliases
fa4763a 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
Specify that --server is required
482fb3c 
Signed-off-by: Andrew Mason <andrew@planetscale.com>
@ajm188 ajm188 merged commit 4450d50 into vitessio:main Jun 14, 2022
@ajm188 ajm188 deleted the andrew/vtctldclient/docsdocsdocs branch June 14, 2022 20:54
ajm188 pushed a commit to planetscale/vitess that referenced this pull request Jun 14, 2022
[vtctldclient] Update CLI docs for usages, flags, and aliases (vitess…
2aaad39 
…io#10502)

* Update docs for backup commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for cell commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for keyspace commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for legacy-shim command

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs, add aliases for reparent commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for root command

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for routing rule commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for schema commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for serving graph commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for shard commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for tablet commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for vschema commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for workflow commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Remove references to deprecated flags

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* fixup! Update docs for keyspace commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Remove reparent command aliases

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Specify that `--server` is required

Signed-off-by: Andrew Mason <andrew@planetscale.com>
@ajm188 ajm188 mentioned this pull request Jun 14, 2022
Merged
3 tasks
ajm188 pushed a commit that referenced this pull request Jun 14, 2022
[vtctldclient] Update CLI docs for usages, flags, and aliases (#10502) (
9c74850 
#10509)

* Update docs for backup commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for cell commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for keyspace commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for legacy-shim command

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs, add aliases for reparent commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for root command

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for routing rule commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for schema commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for serving graph commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for shard commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for tablet commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for vschema commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Update docs for workflow commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Remove references to deprecated flags

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* fixup! Update docs for keyspace commands

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Remove reparent command aliases

Signed-off-by: Andrew Mason <andrew@planetscale.com>

* Specify that `--server` is required

Signed-off-by: Andrew Mason <andrew@planetscale.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@doeg doeg Awaiting requested review from doeg

@notfelineit notfelineit Awaiting requested review from notfelineit

1 more reviewer

@deepthi deepthi deepthi approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

Component: CLI Component: Documentation docs related issues/PRs Type: Documentation

Projects

None yet

Milestone

v14.0

Development

Successfully merging this pull request may close these issues.

2 participants

@ajm188 @deepthi