README.md sucks

Declare what your repo does and how to use it in a structured, yet human-readable schema. Your code repository is an artifact that can receive input and provide output to the outside world. In effect, this means it has an implicit "function signature", and we do ourselves a disservice by attempting to describe these things in prose.

NReilingh/describe-repo-schemaWhat if there was a standardized file at the root of every repo that told you what it was, and what you need to build it? - NReilingh/describe-repo-schema

Sample repo.cue file structure

CUE has a very intuitive and descriptive syntax, while also being far more powerful than YAML or JSON. The schema validator and schema itself are implemented in CUE, which is capable of validating the schema of YAML and JSON files. The suggested convention is to start providing a repo.cue/repo.yaml/repo.json file (per your preferred syntax) at the root of your repository alongside your README.md file.

repovet schema validator

Install

brew install nreilingh/tap/repovet

Validate the closest repo.cue/repo.json/repo.yaml file in the working directory

repovet

Validate a specific file

repovet a_specific_file.cue

Print out the schema sample

repovet sample