风格指南

README

关于 README.md 文件。

1. 概述
2. 可读的 README 文件
3. README 文件应该放在哪里
4. README 文件应该包含什么

概述

README 是目录内容的简短摘要。当您查看包含目录的内容时，文件的内容会显示在 GitHub 和 Gitiles 中。 README 文件为浏览您代码的人（尤其是首次用户）提供关键信息。

本文档介绍如何创建可使用 GitHub 和 Gitiles 读取的 README 文件。

可读的 README 文件

README 文件必须命名为 README.md。 文件名必须以 .md 扩展名结尾，并且区分大小写。

例如，当您查看包含目录的内容时，/README.md 文件会被渲染

https://github.com/google/styleguide/tree/gh-pages

此外，当 Gitiles 显示存储库索引时，HEAD 引用处的 README.md 也会被渲染

https://gerrit.googlesource.com/gitiles/

README 文件应该放在哪里

与所有其他 Markdown 文件不同，README.md 文件不应位于您的产品或库的文档目录中。 README.md 文件应位于您的产品或库的实际代码库的顶层目录中。

代码包的所有顶层目录都应具有最新的 README.md 文件。 对于为其他团队提供接口的包目录，这一点尤其重要。

README 文件应该包含什么

至少，您的 README.md 文件应包含指向您的用户和/或团队文档的链接。

每个包级别的 README.md 都应包含或指向以下信息

1. 此软件包或库中包含什么以及它的用途。
2. 联系方式。
3. 此软件包或库是否已弃用，或者不适用于公开发布等状态。
4. 如何使用软件包或库。 示例包括示例代码、可复制的 bazel run 或 bazel test 命令等。
5. 相关文档的链接。

本网站是开源的。 改进此页面。