Skip to content

[backport] [vtctldclient] Update CLI docs for usages, flags, and aliases (#10502)#10509

Merged
ajm188 merged 1 commit intovitessio:release-14.0from
planetscale:andrew/bp-10502
Jun 14, 2022
Merged

[backport] [vtctldclient] Update CLI docs for usages, flags, and aliases (#10502)#10509
ajm188 merged 1 commit intovitessio:release-14.0from
planetscale:andrew/bp-10502

Conversation

@ajm188
Copy link
Copy Markdown
Contributor

@ajm188 ajm188 commented Jun 14, 2022

Description

This backports #10502 to release-14.0

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

[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 added this to the v14.0 milestone Jun 14, 2022
@ajm188 ajm188 requested a review from deepthi June 14, 2022 20:58
@ajm188 ajm188 requested review from doeg and notfelineit as code owners June 14, 2022 20:58
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jun 14, 2022 •
edited by deepthi
Loading

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.

deepthi
deepthi reviewed Jun 14, 2022
View reviewed changes
go/cmd/vtctldclient/command/keyspaces.go
// CreateKeyspace makes a CreateKeyspace gRPC call to a vtctld.
CreateKeyspace = &cobra.Command{
Use: "CreateKeyspace <keyspace> [--force|-f] [--type KEYSPACE_TYPE] [--sharding-column-name NAME --sharding-column-type TYPE] [--base-keyspace KEYSPACE --snapshot-timestamp TIME] [--served-from DB_TYPE:KEYSPACE ...] [--durability-policy=policy_name]",
Use: "CreateKeyspace <keyspace> [--force|-f] [--type KEYSPACE_TYPE] [--base-keyspace KEYSPACE --snapshot-timestamp TIME] [--served-from DB_TYPE:KEYSPACE ...] [--durability-policy <policy_name>]",
Copy link
Copy Markdown
Collaborator

@deepthi deepthi Jun 14, 2022

Choose a reason for hiding this comment

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

It made sense to remove these flags on main from Use because we have already deleted the underlying functionality.
On 14.0 however, we have only deprecated them, not deleted them. Should we leave them in Use? Or do something like [--sharding-column-name NAME (deprecated) --sharding-column-type TYPE (deprecated)]

Copy link
Copy Markdown
Contributor Author

@ajm188 ajm188 Jun 14, 2022

Choose a reason for hiding this comment

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

I'm gonna argue for "no" (but not super committed to this; happy to take your suggestion if this doesn't convince you!) on the following points:

  1. Not showing in the Use discourages (but does not prevent) people from using the deprecated options
  2. They will still show up in --help
  3. Using the flags will not cause an error and will still print the deprecation warning:
➜  vitess git:(andrew/bp-10502) ✗ ./bin/vtctldclient --server ":15999" CreateKeyspace ks1 --sharding-column-name foobar
Flag --sharding-column-name has been deprecated, Specifying a sharding-column-name on the Keyspace is deprecated and will be removed in a future release.

Copy link
Copy Markdown
Collaborator

@deepthi deepthi Jun 14, 2022

Choose a reason for hiding this comment

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

Ok, I'm convinced that Use should display "recommended" usage versus "deprecated" usage.

@ajm188 ajm188 merged commit 9c74850 into vitessio:release-14.0 Jun 14, 2022
@ajm188 ajm188 deleted the andrew/bp-10502 branch June 14, 2022 23:29
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

Backport This is a backport Component: CLI Type: Documentation

Projects

None yet

Milestone

v14.0

Development

Successfully merging this pull request may close these issues.

2 participants

@ajm188 @deepthi