Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022
Git 存储库应具有自述文件，以便查看者知道代码的作用以及如何开始使用它。 您的自述文件应针对以下受众群体。
- 想要运行代码的用户。
- 想要生成和测试代码的开发人员。 开发人员也是用户。
- 想要将更改提交到您代码的贡献者。 参与者既是开发人员，也是用户。
使用 Markdown 而不是纯文本撰写自述文件。 Markdown 可以轻松地设置文本格式、包括图像以及从自述文件链接到更多文档。
下面是一些使用此格式并针对三个不同的受众编写的自述文件。 用它们进行参考与获取灵感：
先决条件
| 类别 | 要求 |
|---|---|
| 项目访问权限 | 项目的成员。 |
| 权限 | - 查看私有项目中的代码：至少 基本 访问权限。 - 克隆或贡献代码到私有项目中：必须是“贡献者”安全组的成员或拥有项目中的相应权限。 - 设置分支或存储库权限： 管理权限 是分支或存储库的权限。 - 更改默认分支： 编辑策略 是存储库的权限。 - 导入存储库： 项目管理员 安全组的成员或 Git 项目级 “创建存储库 ”权限设置为 “允许”。 有关详细信息，请参阅设置 Git 存储库权限。 |
| Services | 已启用存储库。 |
| 工具 | 可选。 使用 az repos 命令： Azure DevOps CLI。 |
注释
在公共项目中，具有 利益干系人 访问权限的用户具有对 Azure Repos 的完全访问权限，包括查看、克隆和参与代码。
创建简介
请在自述文件的开头添加一个简短说明，描述您的项目。 如果项目具有用户界面，请在简介中添加屏幕截图或动态 GIF。 如果代码依赖于另一个应用程序或库，请确保在简介或正下方声明这些依赖项。 仅在特定平台上运行的应用和工具应具有自述文件本节中记录的受支持操作系统版本。
帮助用户入门
在接下来的 README 文档部分中，指导用户如何在自己的系统上运行代码。 专注于开始编写代码的关键步骤。 链接到任何必备软件的必需版本，以便用户可以轻松访问它们。 如果你有复杂的设置步骤，请在自述文件之外记录这些步骤并链接到它们。
告诉读者在哪里获取最新版本。 提供以下项之一：
- 指向二进制安装程序或预生成包的链接。
- 使用包管理器（例如 npm install、pip install 或 dotnet add 包）的安装说明。
如果项目是库或 API 包装器，请包含显示基本用法的最小代码片段，后跟预期输出。 此信息可帮助读者验证其设置并一目了然地了解库的作用。
为开发人员提供生成步骤
使用自述文件下一部分来显示开发人员如何从存储库的全新克隆生成代码并运行任何包含的测试。 执行以下步骤：
- 提供有关构建代码所需工具的详细信息，并记录配置这些工具以实现干净构建的步骤。
- 将密集或复杂的生成说明分解为文档中的单独页面，并根据需要链接到该页面。
- 在编写说明时，请运行这些说明，以验证说明是否适用于新的参与者。
请记住，您可能是经过一段时间未处理项目后，需要依靠这些指南的开发人员。
包括用于运行生成成功后随源代码一起提供的任何测试用例的命令。 开发人员依靠这些测试用例来确保他们在进行更改时不会破坏代码。 良好的测试用例也可用作开发人员在添加新功能时可用于生成自己的测试用例的示例。
帮助用户参与
自述文件的最后一部分可帮助用户和开发人员参与报告问题并建议改进代码的想法。 用户应该被引导到可以报告 bug、请求新功能或获取代码帮助的渠道。
开发人员需要知道他们需要遵循哪些规则来参与更改，例如编码/测试指南和拉取请求要求。 如果您要求提供贡献者协议以接收拉取请求或执行社区行为准则，则应在本部分链接此过程或记录该过程。 说明发布代码的许可证，并链接到许可证的全文。