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:
https://github.com/google/styleguide/tree/gh-pages
Also README.md
at HEAD
ref is rendered by Gitiles when displaying repository index:
https://gerrit.googlesource.com/gitiles/
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.
Use README.md
.
Files named 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/`. ...