一份检查清单和指南，帮助你的仓库准备好进行协作

我的女儿有一对宠物仓鼠。它们很棒，但并不是最难照顾的生物。它们偶尔需要清理笼子，补充食物和水，如果我们要外出一段时间，可能还需要邻居帮忙照看一下。但有一天，她可能会有一只需要更多照顾和关注的宠物——比如猫或狗，它们每天都需要玩耍和呵护——所以她会希望有几个好朋友了解她的宠物，并在她外出时陪伴它们。有一天，她甚至可能有自己的孩子，这将使她与社区和家庭的联系变得更加重要。正如那句谚语所说，养育一个孩子需要一个村庄。

对于代码项目也是如此。我和我的同事们经常把我们的项目称为“宠物”甚至是“孩子”（有时是开玩笑，有时是认真的）。我们投入了很多自己的关怀和关注，但有时会忘记社区的贡献对项目的成功有多么重要。在软件开发的世界里，协作可以决定一个项目是成为一个脆弱的临时发布，还是一个可靠、可维护且无痛的项目。无论你是编程一天还是十年，你的同事都在那里帮助你提升工作质量。但前提是，你必须给他们提供帮助的工具。

作为仓库的创建者或维护者，您的主要责任是确保他人能够适当地使用、理解并甚至为项目做出贡献。GitHub 会支持这一使命，但确保一个仓库能够进行协作需要比使用 git clone 更多的努力。继续阅读以了解有助于您成功的设置、内容和行为。

您的仓库的设置为协作奠定了基础。它们决定了谁可以查看和贡献您的项目，贡献如何被审查，以及提交后的贡献会发生什么。正确使用这些设置可以营造一个环境，让全球的贡献者找到、利用并帮助构建您的项目。在企业环境中，这些设置有助于将开发人员从孤立的工作方式转变为“优先搜索、优先协作”的思维方式。这种做法被称为innersourcing，可以减少重复工作并加速整个公司的运作。

可见性

你旨在最大化贡献和重用，但这并不总是意味着要将仓库公开，特别是在企业环境中，信息隐私是一个需要考虑的因素。你可以在仓库的“设置”标签中找到几个可用的选项。

• 公开 允许全世界的人查看和复制你的代码，并通常允许他们创建问题或拉取请求，以便他们可以提供关于代码是否运行良好的反馈，甚至建议（但不能强制）改进的更改。这通常非常适合不包含任何受保护信息的个人项目（那些令牌都单独存储吧？），但仅适用于某些“受祝福”的公司项目。
• 内部 是一种特殊可见性级别，由GitHub Enterprise 使用，允许组织内部的任何人都查看仓库，但不允许外部人员查看。我们通常建议将此级别作为公司项目（不包含隔离的敏感信息，如特定客户的特定数据或只有特定小组应该知道的逻辑）的默认级别。
• 私有 是最严格的选项，可能会限制协作。请谨慎使用此选项，如果使用，请务必邀请一些协作者。
• 协作者 是你邀请加入项目的特定个人或团队。你可以给他们分配特定的角色，例如“读取”（允许他们查看你的私有仓库）、“写入”（允许他们直接提交或管理拉取请求）、“管理员”，以及其他许多角色。

保护主分支

虽然你希望尽可能多的人能看到并为你的项目做出贡献，但仍需确保他们的贡献能够被妥善审查，不仅由你核心团队成员进行审查，还需要通过自动化工具进行审查。在大多数情况下，你希望在主分支上创建一个仓库规则（这是分支保护的现代替代品），并配置它要求在允许合并之前必须有一个拉取请求。通过要求至少有一个审批人，最好是来自你的CODEOWNERS文件中的一员（将在下一节讨论），你将确保每组更改都有另一名人类审阅者。此外，你还希望自动化工具（如单元测试）针对每个拉取请求运行；这些被称为状态检查，将在“自动化和检查”部分中进行介绍。

软件项目不仅仅由代码组成。你的仓库应该作为一个协作指南，让协作者了解它的存在原因、如何正确使用它以及如何有效地进行贡献。添加一些关键文件（通常使用Markdown编写）将帮助其他人发现你的项目并理解如何有效地进行协作。

README.md：这是访客进入您的仓库后首先看到的文件，因此将其包含在仓库中非常重要。它应该描述您的项目做什么，如何使用仓库，以及所需的任何配置。此外，一个好的README还应包括项目的使命、目标以及存在的原因。最后，务必描述项目是如何以及由谁维护的。

LICENSE.md: 许可证文件定义了他人可以和不可以对你的代码和其他内容做什么。无论你的目标是允许你的项目不受限制地使用，还是对它的使用和分发添加特殊限制，包含一个许可证都是至关重要的。访问 choosealicense.com 获取关于哪种许可证最适合你的项目的指导，然后 添加一个许可证 到你的仓库。

CONTRIBUTING.md：你可以通过清晰地定义为什么以及如何让潜在贡献者（包括你自己）为项目贡献新的代码、文档、艺术作品或其他元素，来减少困惑和摩擦。如果贡献步骤非常简单，你可以在README中包含它们；但如果发现需要超过一段或两段文字（通常会超过），最好创建一个单独的文件。该文件应包括你希望的贡献类型、如何提议新功能或修复错误、提交拉取请求的过程，以及贡献者应遵循的任何特定编码标准或风格指南。你可以参考GitHub文档项目的贡献者指南作为良好示例。

CODEOWNERS: CODEOWNERS 文件 用于分配一个或多个用户，这些用户将负责仓库中特定部分的代码。根据仓库设置，当有人打开一个修改了他们负责代码的拉取请求时，这些人员将自动被请求进行审查。请注意，此文件与这里提到的其他文件不同，不应带有“ .md ”扩展名。

CODE_OF_CONDUCT.md: 行为准则确立了项目参与者应遵循的社会规范、规则和责任。它促进了友好和尊重的协作环境，而且很容易通过手动添加或使用GitHub提供的模板来添加！

有了这些文件，你的仓库将变得更加易于接近和理解，你应该会开始看到更多的贡献。但如果你想做得更多，你可以采取更多措施来为健康的贡献设置你的项目。

是时候进入矩阵了。正如史密斯特工常说的，“不要让人来做机器能做的工作。”虽然你通常希望每个主要变更至少有一个人工审核者，但你应该尽量让他们的工作尽可能简单。GitHub 内置的自动化和 CI/CD 系统，GitHub Actions，允许你在文件更改、拉取请求、外部触发器（如聊天工具）甚至定时任务时运行工作流。让我们看看这如何让合作者的生活更轻松。

代码检查

代码检查工具（Linters）用于分析代码以检测各种类型的错误并强制执行一致的编码风格。将代码检查工具纳入您的开发流程可以极大地提高代码的可读性和质量，使其更容易让他人理解和贡献到您的项目中。其中最流行的一个是Super-Linter，它可以通过一个简单的复制粘贴步骤进行初始配置。

构建和测试

虽然你运行的确切编译器和测试套件将取决于你的应用程序所使用的语言和框架，但大多数都可以在你的仓库中自动执行。要找到合适的工具，请在 GitHub Marketplace 的 构建 和 测试应用与操作 列表中进行搜索，然后按照你所选择的工具的具体说明进行操作。或者，你也可以通过在你的 GitHub Actions 工作流中 运行命令行脚本和参数 来执行它们。

检查

当信息直接在拉取请求中呈现给审阅者时，这会使他们的工作更快更轻松，无需手动运行测试套件或手动检查清单。如果自动检查失败，您甚至可以阻止部署。一旦您按照上述方法添加了代码检查器或测试套件，并且 它至少运行过一次 ，请考虑将其配置为仓库设置中的状态检查。这将有助于确保每次创建拉取请求时您的应用程序都能得到适当的测试。

这并不是一个完整的列表，但每个项目都是不同的，因此还需要考虑你可能想要包含的其他 代码质量、依赖管理 或 预发布自动化 工具。然后，考虑你希望如何部署项目。在大多数情况下，你会发现 GitHub 市场 中有一个组件可以提供与你最喜欢的基础设施提供商的开箱即用集成，但你也可以编写自己的 GitHub Actions 来在所有检查通过后部署你的应用。对于高流量的企业项目，如果开始出现快速变化分支上的交通拥堵，可以考虑使用 合并队列。

有了这些自动化工具和检查，你可以更加自信地保证对仓库的贡献的质量和一致性，并且可以减少手动管理流程所花费的时间。

在任何软件项目中，安全都是首要关注点，尤其是在包含各种不同安全培训水平（或完全没有接受过培训）的合作者时，这一点尤为重要。幸运的是，你可以采取一些简单的步骤来保护你的代码、数据和用户免受潜在威胁。

角色

仔细决定你给仓库合作者分配哪些角色，以及相应的权限。一般而言，你会希望将“读取”角色分配给公众。“审阅”和“写入”角色适用于值得信赖的个人，例如你的公司成员或工作小组成员（但前提是已经设置了保护分支和检查）。而“维护”和“管理员”角色最适合你的核心维护者，他们负责审查和管理进入生产环境的内容。“审阅”及以上的角色可以管理问题、讨论和评论，因此你需要信任他们有承担这些职责的承诺和背景。企业客户可以利用自定义仓库角色来实现更细粒度的权限控制。

秘钥管理

敏感数据如API密钥、密码和证书等都需要保密。你不希望这些数据直接嵌入到代码或日志中；相反，你应该使用第三方密钥库或GitHub的内置密钥管理工具，这些工具可以在你的仓库设置中的“密钥和变量”部分找到。在那里，你会找到分别针对GitHub Codespaces（在下面的“高级选项”部分中描述的工具）和GitHub Actions的独立部分，因为你在开发过程中可能希望使用不同于生产环境的密钥。

安全扫描工具

代码扫描漏洞是一个复杂的话题，但可以分为三大类。

• 依赖项：大多数应用程序的代码中有80-90%来自第三方来源——我们构建其余代码所依赖的框架和包。GitHub Dependabot 可用于所有公共仓库，并可以通过 自动启用 在整个组织中启用。它能够在发现不安全的依赖项时提醒你（并帮助提供修复方案）。为了确保 Dependabot 正在运行，请检查仓库顶部的“安全”标签。你还可以启用 依赖项版本更新，以便在新版本的包可用时通知你，即使没有明确识别出漏洞，你也可以保持最新状态。

• 密钥：虽然你应该已经在上面描述的步骤中使用了密钥管理器，但我们都会犯错，一些令牌可能会被嵌入到代码中而未被发现。通过 密钥扫描 工具，无论是通过 第三方集成 还是通过 GitHub Advanced Security 为企业提供的工具，都可以在将密钥令牌推送到仓库时通知你甚至阻止这些令牌。

• 新型漏洞：当你编写新代码时，可能会无意中添加新的漏洞，这些漏洞可能存在于新代码本身或现有组件的连接方式中。有许多 广泛的方法 可以扫描整个应用程序，其中一些方法依赖于语言。企业还可以依靠 GitHub Advanced Security 的 代码扫描 来发现各种漏洞，从 SQL 注入到循环引用，支持 大多数流行编程语言。

SECURITY.md 和私有漏洞报告

如果用户或安全研究人员发现了您项目中的问题，他们需要知道如何安全且负责任地报告这些问题。请在您的仓库中包含一个安全政策文件，以提供这些指导方针并帮助维护您用户和更广泛社区的信任。同时，开启私有漏洞报告，这将允许安全研究人员安全地报告他们发现的任何漏洞！

除了基础功能之外，您还可以利用一系列高级选项来进一步增强仓库的协作准备程度。

问题模板

随着合作者使用你的项目，他们将会提交问题请求修复错误和增强功能。默认情况下，这些请求可能比较松散，你可能需要多次与创建者沟通以获取所需的所有信息。通过创建几个问题模板，你可以提供指导，定义用户将看到的必填和选填字段，并设置他们在打开问题时选择的特定选项。

GitHub Codespaces 配置

GitHub Codespaces 提供了一个基于仓库的完整且可配置的开发环境。这使得任何人都可以从任何地方参与你的项目，而无需设置本地环境。提供一个配置良好的代码空间 可以让其他人更容易地为你的项目做出贡献，并且由于所有开发人员都将从相同的配置开始工作（消除了“在我的机器上可以运行但在你的机器上不行”的问题），因此可以减少项目的脆弱性。

环境

GitHub 环境 允许您指定某些任务（如部署）应在何处执行。它们可以配置为具有特定的保护规则，确保重要任务仅在受控和安全的环境中执行。

现在你已经设置了你的仓库，是时候考虑更广泛的协作方面了，包括你作为维护者的角色以及你如何与你的社区互动。

响应性

作为维护者，您的响应能力在促进健康、协作的环境中起着至关重要的作用。这包括及时处理问题和拉取请求，提供反馈，并指导新贡献者。请每周预留特定时间来回应变更并解决存在的问题。如果您想衡量项目的响应能力，可以查看 Metrics Action。

项目管理

GitHub 自带的 项目规划 功能既适用于单个项目，也适用于企业级协作。通过设置 GitHub Projects 来管理您的工作，并向您的社区提供透明度。这不仅有助于您保持组织性，还让其他人能够了解项目的当前状态并找到可以贡献的地方。

可见性

一个维护良好的仓库如果没有被人知晓就毫无用处。你可以通过撰写博客文章、演示或专门的项目门户网站来推广你的项目。知道你项目的人越多，你吸引潜在贡献者和用户的可能性就越大。

社区参与

与社区互动是营造健康、协作环境的关键。这可能包括组织聚会、运营项目博客，甚至只是积极参与讨论。

通过遵循这些标准，您可以确保您的仓库不仅仅是为了协作而准备的，还是一个充满活力的社区可以繁荣发展的场所！打印出此检查表，并在每次创建（或重新访问）GitHub仓库时使用它来帮助引导您。

下载 此可打印检查表，以确保您涵盖了使仓库准备好协作的所有方面。或者，使用此方便的 问题模板 在您自己的 GitHub 仓库中创建一个可更新的检查表！