为开源做贡献

了解如何向开源项目作出贡献，以便被维护者接受。

本文内容

在本文中，您将通过示例学习如何为开源项目作出贡献。我们将指导您对 github/docs 仓库进行贡献：熟悉仓库、寻找可贡献的领域、创建并提交拉取请求，以及与维护者合作以让您的更改被接受。

熟悉项目指南

在开始之前，了解项目的指南和要求非常重要。

为什么指南重要？

每个项目都有自己的约定、编码标准和贡献流程，您需要遵循它们

  • 代码风格与格式要求：代码应如何格式化、命名约定以及 lint 规则
  • 测试指南：如何运行测试、新功能需要哪些测试以及测试约定
  • 拉取请求流程：如何组织拉取请求、需要包含哪些信息以及审查期望
  • 开发环境设置：如何搭建本地开发环境、所需依赖以及构建流程
  • 问题报告：如何报告错误、申请功能或提出问题
  • 沟通渠道：在哪里提问、讨论更改或获取维护者帮助

花时间阅读这些内容会为您和维护者节省时间，并且更有可能让您的贡献被接受。

查找指南

要访问这些指南和要求，请在 Insights（洞察）选项卡中打开 Community Standards（社区标准）清单。以我们的示例为例，我们将使用 github/docs 社区标准。

  • README：提供项目概览。内容可能有所不同，但 README 帮助用户和贡献者快速了解项目是什么以及如何使用，并提供其他文档的链接。

  • 行为准则：定义了项目贡献者和社区成员的可接受行为标准，并建立了处理违规的期望和程序。

  • Contributing（贡献指南）：为项目贡献者提供指南和说明。通过设定明确的期望并鼓励一致的协作，帮助简化贡献流程。

  • 许可证：在法律上定义了他人如何使用、修改和分发代码，通过明确版权和许可条款来保护维护者和用户的权益。

    • 例如，github/docs 仓库对文档使用的是 Creative Commons（知识共享）许可证，这是一种专门针对创意作品的许可证。github/docs 中的软件代码则采用 MIT 许可证，这是一种宽松的许可证，允许任何人使用其中的代码。
    • 您可以使用 Choose a license 工具了解其他常见许可证类型。

  • 安全策略：提供向仓库维护者报告安全漏洞的说明。

审阅 github/docs 仓库可用的各项资源。

寻找可贡献的领域

首次为项目贡献时，从文档改进或小型错误报告等小修小改开始，有助于您熟悉代码库和贡献者工作流。在本示例中，您将通过使用 help wanted（需要帮助）和 good first issue（适合新人）标签来查找适合外部贡献者的特定问题。随后您将使用 Copilot 为该问题提供上下文。

  1. 进入 github/docs 仓库的 Issues（问题）标签页，然后使用 Labels（标签）过滤器并选择 “help wanted”，即可查看维护者特别标记为需要社区帮助的开放问题。

  2. 浏览问题列表，找到您感兴趣的可着手处理的问题。

  3. 前往 https://github.com/copilot。

  4. 在提示框中输入以下提示内容

    Text
    Can you summarize the key points and next steps from this issue?

  5. 阅读 Copilot 提供的上下文，以及其他贡献者和维护者的评论，判断该问题是否是您想要处理的。如果有具体问题，您可以直接在 issue 中提问，或在项目的 Discord、IRC 或 Slack（如适用）中询问。

提示

如果您在没有 help wanted 或 good first issue 标签的 issue 上工作，最好在该 issue 中询问维护者您是否可以提交拉取请求，以确认您的计划贡献符合项目目标。

创建项目的自己的副本

现在您可以开始贡献了。由于您没有编辑仓库的权限，首先需要创建一个 fork（分叉）：这是一份您自己的仓库副本，您可以在其中安全地进行更改并提交给维护者审查。在本示例中，我们将演示如何为 github/docs 仓库创建分叉。

  1. 前往 GitHub Docs 项目，网址为 https://github.com/github/docs。

  2. 在页面右上角，单击 Fork。

  3. 在 “Owner” 下，打开下拉菜单并选择 Fork 后仓库的拥有者。

  4. 默认情况下，Fork 的名称与其上游仓库相同。若想进一步区分你的 Fork，可在 “Repository name” 字段中输入自定义名称。

  5. 可选地，在 “Description” 字段中输入对你的 Fork 的描述。

  6. 可选地，选中 仅复制默认分支（DEFAULT）。

    在许多 Fork 场景（如为开源项目贡献）中，你只需复制默认分支。如果不选此项，则所有分支都会复制到新 Fork 中。

  7. 单击 Create fork。

克隆项目的分叉

现在您在账户下拥有了 github/docs 仓库的分叉，但需要将其克隆到本地机器，才能开始进行更改。

  1. 在 GitHub 上，前往 github/docs 仓库的 您的分叉。

  2. 在文件列表上方，点击 代码。

    Screenshot of the list of files on the landing page of a repository. The "Code" button is highlighted with a dark orange outline.

  3. 复制该仓库的 URL。

    • 要使用 HTTPS 克隆仓库，请在“HTTPS”下点击.

    • 要使用 SSH 密钥克隆仓库（包括由您组织的 SSH 证书颁发机构签发的证书），点击 SSH，然后点击.

    • 要使用 GitHub CLI 克隆仓库，点击 GitHub CLI，然后点击.

      Screenshot of the "Code" dropdown menu. To the right of the HTTPS URL for the repository, a copy icon is outlined in dark orange.

  4. 在 macOS 或 Linux 上，打开终端（Terminal）。在 Windows 上，打开 Git Bash。

  5. 将当前工作目录切换到希望放置克隆目录的位置。

  6. 输入 git clone，随后粘贴之前复制的 URL。它的形式类似于下面这样，只需将其中的 YOUR-USERNAME 替换为你的 GitHub 用户名。

    Shell
    git clone https://github.com/YOUR-USERNAME/docs

  7. 按 Enter 键。将创建本地克隆。

在主题分支中进行更改

现在是进行更改的时候了！在开始之前，建议在您的分叉中创建一个带有 描述性名称 的 主题分支。使用主题分支可以让您的工作与仓库的默认分支分离。

Shell
git checkout -b YOUR_TOPIC_BRANCH

切换到您的主题分支后，打开您喜欢的文本编辑器或 IDE，开始编码。请遵循以下最佳实践：

  • 使用 Copilot 提供代码建议，让您对更改更有信心。
  • 为代码编写文档并编写测试。这些常被忽视，但有助于确保您的贡献能够合并。
  • 向 Copilot 提问该 issue，以帮助您进一步了解实现需求。
  • 使用 Copilot 审核您的更改，确保符合项目的代码风格和文档要求。
  • 使用 Copilot 获取在本地机器上构建和测试项目的指令帮助。

提交并推送更改

当更改完成后，您可以在仓库中暂存并提交它们。编写提交信息时，请使用简洁明确、长度不超过 50 字符的标题，概括本次提交的内容。尽可能将相关更改合并为单个提交，但应将无关更改分开提交。

Shell
git add .
git commit -m "a short description of the change"

为提升可读性，尽量将提交说明的每行保持在 72 字符以内。当您完成本地更改的提交并准备将其推送到 GitHub 时，请将更改推送到远程仓库。

Shell
git push

提交拉取请求

现在您已经将更改推送到 GitHub，接下来可以打开拉取请求。即使您尚未完成分支中的所有更改，也可以打开拉取请求进行审阅。提前打开拉取请求可以让维护者了解您的进展，并提供对您更改的初步反馈。

  1. 前往您在 GitHub 上的分叉仓库。例如，https://github.com/YOUR-USERNAME/docs。
  2. 您应该会看到针对最近推送的分支出现 “Compare & pull request”（比较并创建拉取请求）的提示，点击它。
  3. 如果没有，前往 “Pull requests”（拉取请求）标签页，点击 “New pull request”（新建拉取请求）。
  4. 确保 base（基准） 仓库为 github/docs，且基准分支为其主分支（例如 main）。
  5. 确保 head（头部） 仓库为您的分叉（YOUR-USERNAME/docs），且比较分支为您所使用的分支。
  6. 为您的拉取请求填写标题和描述。在描述中引用您将要关闭的 Issue，例如 Closes: #15。这将为拉取请求提供上下文，并在拉取请求合并后自动关闭对应的 Issue。

提示

在拉取请求提交审阅后，避免使用强制推送（force push），因为这会使维护者更难看到您对反馈的处理情况。

与项目维护者合作

提交拉取请求后，下一步是项目维护者进行审阅并提供反馈。维护者可能会要求您更改代码以符合代码库的风格或架构，有时需要您对工作的大部分内容进行重构。

  • 当收到关于您拉取请求的反馈时，请及时且专业地作出回应，即使批评显得严厉。维护者通常关注代码质量。
  • 如果对您的拉取请求提出修改请求，请不要另开新拉取请求来处理这些更改。保持原有拉取请求打开状态并在其上进行修改，有助于维护者保持上下文。
  • 如果您的拉取请求数周未得到处理，请礼貌地留下评论请求反馈。不要直接标记维护者的账号。维护者通常需要在全职工作与开源贡献之间平衡，理解他们的时间限制有助于更好地合作。
  • 如果您的贡献未被接受，请向维护者寻求反馈，以便在下一次贡献时能够参考这些信息。

后续步骤

现在您已经了解如何识别合适的 Issue、打造维护者愿意合并的贡献，以及如何顺利进行拉取请求审阅流程。GitHub 上的开源社区期待您的独特视角和技能。寻找一个令您兴奋的项目，确定要处理的 Issue，开始贡献吧。

© . This site is unofficial and not affiliated with GitHub, Inc.