pingcap / pingcap/tiup

Usage docs for root.json file need improvement

Open
#1,300 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

category/document category/usability 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:

#829 already requested improvements in this area, but I think we must do a much better job of explaining the functionality of root.json.

After cloning https://github.com/pingcap/tiup.git and executing make, the behavior of the newly-built tiup executable is extremely confusing.

# ./bin/tiup list
Error: initial repository from mirror(https://tiup-mirrors.pingcap.com/) failed: cannot open the initial root.json at /root/.tiup/bin/root.json

Describe the feature you'd like:

We should do a couple things:

  1. Give a clearer explanation in tiup output when root.json cannot be found. There should be an explanation of what this file does and a link to documentation that describes where it comes from and how to get it.
  2. Documentation (in docs.pingcap.com) that explains root.json by itself should be created. Today, the only mentions of root.json are in the documentation about creating a mirror, but tiup refuses to do almost anything if that file is missing.

Describe alternatives you've considered:

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

Start with the behavior exposed by make and bin/tiup list when /root/.tiup/bin/root.json is missing. Review the existing root.json references in the mirror documentation and the docs.pingcap.com structure. Done means the CLI explains the file and how to obtain it, and standalone documentation covers its purpose and source.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.