pingcap / pingcap/tiup

Show some examples or link to the doc page in `tiup cluster help`?

Open
#975 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type/feature-request
Dominant language
Go
Stars
466
Forks
338
Avg merge
3d 7h
Merged PRs (30d)
8

Description

Feature Request

Is your feature request related to a problem? Please describe:

So when we run tiup cluster help, we get a list of subcommands and options, which is fine, but to a complete newbie they are total lost what to do next 🤷. This is unlike tiup itself or tiup playground which contains some examples to start with.

Describe the feature you'd like:

Since tiup cluster requires a config file, I doubt playground-like examples would be sound. But it should be good if we point to the docs in the help page like:

$ tiup cluster --help
Deploy a TiDB cluster for production

See <https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup> for how to start.

Usage:
  tiup cluster [command]

...

Describe alternatives you've considered:

There could also be a example-topology command to which generates an example topology.yaml file, thus allowing an Example section

$ tiup cluster example-topology minimal > topology.yaml; vi topology.yaml  # prepare topology config
$ tiup cluster deploy tidb-test v4.0.10 ./topology.yaml --user root        # deploy the cluster, ssh-login as 'root'
$ tiup cluster start tidb-test                                             # start the cluster
$ tiup cluster display tidb-test                                           # check cluster status 

Teachability, Documentation, Adoption, Migration Strategy:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the tiup cluster help implementation and compare its output with tiup and tiup playground help. Add either the production-deployment documentation link or a clearly usable example, then run the relevant CLI help checks to confirm the output guides a new user.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
40/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.