为存储库创建 READM

  • 项目

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Git 存储库应有一个自述文件，以便查看者了解代码的功能以及如何开始使用它。 自述文件应面向以下受众：

  • 只想运行代码的用户。
  • 想要生成和测试代码的开发人员。 开发人员也是用户。
  • 想要向代码提交更改的参与者。 参与者既是开发人员，也是用户。

使用 Markdown 而不是纯文本编写自述文件。 通过 Markdown，可以轻松设置文本格式、包含图像，并根据需要链接到自述文件中的更多文档。

以下是一些使用这种格式并面向所有三类受众的出色自述文件，以供参考和启发：

创建简介

自述文件的开头要有一个简短的项目说明。 如果项目具有用户界面，请在简介中添加屏幕截图或动态 GIF。 如果代码依赖于其他应用程序或库，请确保在简介或其下方声明这些依赖项。 仅在特定平台上运行的应用程序和工具应具有自述文件本部分中注明的受支持操作系统版本。

帮助用户入门

在自述文件的下一节中指导用户在自己的系统上启动和运行代码。 专注于开始使用代码的基本步骤。 链接到任何必备软件的所需版本，以便用户可以轻松访问它们。 如果有复杂的设置步骤，请在自述文件之外记录这些步骤并链接到它们。

指出从何处获取最新版本的代码。 最好使用二进制安装程序或有关通过打包工具使用代码的说明。 如果你的项目是 API 的库或接口，请放置一个显示基本用法的代码片段，并在该代码片段中显示代码的示例输出。

为开发人员提供生成步骤

使用自述文件的下一部分向开发人员展示如何从存储库的全新克隆生成代码并运行任何包含的测试。 请执行以下操作：

  • 提供有关生成代码所需工具的详细信息，并记录配置这些工具以获取干净生成的步骤。
  • 将密集或复杂的生成说明分解到文档中的单独页面中，并在需要时链接到该页面。
  • 在编写说明时从头到尾运行这些说明，以验证这些说明是否适用于新参与者。

请记住，如果你有一段时间没有处理项目，那你也可能要依靠这些说明。

提供命令以在生成成功后运行源代码提供的任何测试用例。 开发人员依赖于这些测试用例，以确保他们在进行更改时不会破坏你的代码。 好的测试用例还可以作为示例，开发人员可以在添加新功能时使用这些示例来构建自己的测试用例。

帮助用户参与

自述文件的最后一部分可帮助用户和开发人员参与报告问题，并提出改进代码的想法。 应将用户链接到可以打开 bug、请求功能或获取使用代码相关帮助的通道。

开发人员需要知道他们需要遵循哪些规则来贡献更改，例如编码/测试指南和拉取请求要求。 如果需要参与者协议来接受拉取请求或强制实施社区行为准则，则应将此过程链接到或记录在本部分中。 说明代码是根据什么许可证发布的，并链接到许可证的全文。