Usage docs for root.json file need improvement
Nobody has claimed this yet.
- 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:
- Give a clearer explanation in
tiupoutput 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. - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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