About README.md files.
README.md files are Markdown files that describe a directory. GitHub and Gitiles renders it when you browse the directory.
For example, the file /README.md is rendered when you view the contents of the containing directory:
HEAD ref is rendered by Gitiles when displaying repository index:
README.md files are intended to provide orientation for engineers browsing your code, especially first-time users. The
README.md is likely the first file a reader encounters when they browse a directory that contains your code. In this way, it acts as a landing page for the directory.
We recommend that top-level directories for your code have an up-to-date
README.md file. This is especially important for package directories that provide interfaces for other teams.
README are not displayed in the directory view in Gitiles.
At minimum, every package-level
README.md should include or point to the following information:
# APIs This is the top-level directory for all externally-visible APIs, plus some private APIs under `internal/` directories. See [API Style Guide](docs/apistyle.md) for more information. *TL;DR*: API definitions and configurations should be defined in `.proto` files, checked into `apis/`. ...