About files.

  1. Overview
  2. Guidelines
  3. Filename
  4. Contents
  5. Example

Overview files are Markdown files that describe a directory. GitHub and Gitiles renders it when you browse the directory.

For example, the file / is rendered when you view the contents of the containing directory:

Also at HEAD ref is rendered by Gitiles when displaying repository index:

Guidelines files are intended to provide orientation for engineers browsing your code, especially first-time users. The 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 file. This is especially important for package directories that provide interfaces for other teams.



Files named README are not displayed in the directory view in Gitiles.


At minimum, every package-level should include or point to the following information:

  1. What is in this package/library and what's it used for.
  2. Who to contact.
  3. Status: whether this package/library is deprecated, or not for general release, etc.
  4. More info: where to go for more detailed documentation, such as:
    • An file for more detailed conceptual information.
    • Any API documentation for using this package/library.


# APIs

This is the top-level directory for all externally-visible APIs, plus some
private APIs under `internal/` directories.
See [API Style Guide](docs/ for more information.

*TL;DR*: API definitions and configurations should be defined in `.proto` files,
checked into `apis/`.