每个好的 README 应该包含什么

我在一家大型工程组织工作，那里有数千个活跃的仓库。由于我目前职位的特殊性，我每周都会接触几个新的仓库，而不是只接触其中几个。这每周都需要学习大量的新信息！对我来说，完全熟悉我接触的每个仓库的细节并不现实，但有一些核心信息我几乎总是需要了解的。理想情况下，这些信息应该包含在每个仓库的 README 文件中。

那么，README 中应该包含哪些信息呢？每个好的 README 至少应该包含以下内容：

1. 这个 repo 是什么或者做什么
2. 如何在本地运行项目
3. 如何运行测试
4. 如何将合并的更改纳入更大的应用程序
5. 您认为对于您的特定 repo 有帮助的任何其他信息
6. 任何其他资源的链接

让我们简单了解一下这些项目以及它们为何重要。

这个 repo 是什么或者做什么

README 应该为开发者建立一些背景信息。这个仓库是什么？它做什么？这个仓库的用途是什么？它解决了什么问题，或者提供了什么功能？几段高层次的概述可以帮助开发者了解所有可能想要了解的内容。

如何在本地运行项目

现在开发人员知道了 repo 是什么，他们如何运行它？

他们需要先安装任何依赖项或运行安装脚本吗？对于前端应用来说，这希望只需运行yarn install(或npm install) 即可。

设置完成后，如何在本地启动应用？如果应用可以在像 Storybook 这样的独立沙盒环境中运行，请提供相关说明。这可以像运行 一样简单yarn start:storybook。

那么在大型应用的环境中运行该应用怎么样？对于拥有多个代码库的组织来说，通常将每个较小的代码库发布为 npm 包，然后每个包作为依赖项安装在较大的父应用中。

那么，如何在本地运行这个较小的应用，以便在发布新版本之前查看新的更改呢？具体方法可能包括使用类似yarn link或 之类的命令链接依赖yalc项。或者，您可以使用像 Resource Override 这样的浏览器扩展程序来覆盖浏览器中打包的 JS 文件。又或者，这个应用是一个微前端，您只需使用类似 的命令启动应用yarn start，然后覆盖所用资源的 URL 即可。

如何运行测试

开发人员知道应用程序的功能以及如何运行它，但是测试呢？理想情况下，运行测试套件就像运行程序yarn test或其变体一样简单。

有时，在运行测试之前需要进行一些隐藏的设置，因此将这些信息标注出来会很有帮助。例如，您可能使用 Cypress 运行集成测试，但运行 Cypress 测试的一个隐含前提条件是应用需要先在本地运行。如果测试脚本尚未启动应用，则应确保记录预期的测试设置。

如何将合并的更改纳入更大的应用程序

开发人员能够运行应用程序和测试，并且他们成功地对代码进行了一些更改。接下来该怎么办？他们如何将这些更改合并到更大的应用程序中？您需要确保记录您的分支策略以及合并请求流程。

代码合并后，接下来会发生什么？如果这是一个 npm 包，新版本会在合并后的流水线中自动发布吗？还是需要开发人员手动发布新版本？如果这是一个微前端，合并后变更会自动部署吗？还是需要开发人员手动启动流水线来执行此操作？

您认为对于您的特定 repo 有帮助的任何其他信息

通过前面四点，我们涵盖了所有开发者需要了解的基础知识。他们了解了项目背景，并能够成功运行、测试和部署应用程序。

还有什么需要他们了解的吗？这很难写出通用的指导，但你的代码库肯定有一些不为人知的特殊之处。除了master或main分支之外，你是否使用了独特的分支策略或任何特殊分支？你是否有任何特殊的 linter 或提交设置需要大家注意？在流水线或部署方面，有什么需要注意的陷阱吗？如何与其他代码库耦合？这个代码库是否与其他代码库紧密结合使用？

记录这些隐藏的宝石非常有用，这样它们就不会仅仅停留在部落知识的层面上。

任何其他资源的链接

最后，还有其他文档或 wiki 页面是开发者可能感兴趣的吗？也许你使用了 Notion 或 Confluence 之类的工具，并且在那里记录了更多信息。请务必添加指向 README 中未包含但可能很重要的任何其他信息的链接。

结论

README 旨在帮助新开发者顺利使用你的代码库。当开发者掌握了所需的所有背景信息和开发环境时，他们会更加独立。他们不太可能向你提出问题，你也不必再重复之前的步骤。这对所有参与者来说都是有益的。