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