为开放源代码做出贡献

在本文中，你将通过完成一个示例学习如何为开放源代码项目做出贡献。 我们将指导你对 github/docs 仓库做出贡献：熟悉仓库、找到要贡献的区域、创建和提交拉取请求，以及与维护者合作以使你的更改被接受。

熟悉项目指南

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

为什么指导方针很重要？

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

• 代码样式和格式设置要求：应如何设置代码格式、命名约定和 Lint 分析规则****
• 测试准则：如何运行测试、新功能需要进行哪些测试以及测试约定****
• 拉取请求流程：如何构建拉取请求、要包含哪些信息以及审核预期****
• 开发设置：如何设置本地开发环境、所需依赖项和生成流程****
• 议题报告：如何报告 bug、请求功能或提问****
• 沟通渠道：在哪里提问、讨论变更或获得维护者的帮助****

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

查找准则

要访问这些准则和要求，请导航到“Insights”选项卡中的“Community Standards”清单********。在我们的示例中，我们将使用 github/docs 社区标准。

• README：提供项目概述****。 内容可能有所不同，但 README 可帮助用户和参与者快速了解项目内容以及如何使用它，并提供其他文档的链接。

• 行为准则：为项目参与者和社区成员定义可接受行为标准，并建立解决冲突的期望和过程****。

• 贡献：为项目参与者提供准则和说明****。 它通过设置明确的期望并鼓励持续协作，帮助简化贡献过程。

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

  • 例如，github/docs 仓库对文档使用了 Creative Commons 许可证，这是一种专门针对创意作品的许可证类型。 github/docs 中的软件代码已获 MIT 许可证的许可，该许可证是一种宽松的许可证，允许任何人使用其中包含的代码。
  • 可以使用选择许可证工具了解其他常见的许可证类型。

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

查看可用于 github/docs 仓库的每个资源。

查找要对其做出贡献的领域

首次为项目做贡献时，从文档改进或报告小 Bug 等小修复开始，这可以帮助熟悉代码库和参与者工作流。 在此示例中，你将使用 help wanted 和 good first issue 标签来查找议题，以显示对外部参与者开放的特定议题。 然后，使用 Copilot 来帮助提供有关该议题的上下文。

1. 导航到 github/docs 仓库的“Issues”选项卡，然后使用“Labels”筛选器并选择“help wanted”，以查看维护者明确标记为需要社区帮助的未决议题********。

2. 浏览议题列表并找到你感兴趣的议题。

3. 在 GitHub 上的任意页面的右上角，单击搜索栏旁边的 按钮****。

   随即将显示 Copilot 对话助手 的完整页面沉浸式模式。

4. 在提示框中输入以下提示：

   Text

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

5. 阅读提供的上下文 Copilot，以及其他参与者和维护者的评论，看看该议题是否是你想要解决的议题。 如果有特定议题，可以直接在议题中或在项目的 Discord、IRC 或 Slack 中询问（如果适用）。

创建项目的副本

现在你已准备好开始做出贡献。 由于你无权编辑仓库，因此首先需要创建一个派生：你自己的仓库副本，可以在其中安全地进行更改并将其重新提交给维护者进行审查****。 在此示例中，我们演练如何创建 github/docs 仓库的派生。

1. 导航到位于 https://github.com/github/docs 的 GitHub Docs 项目。

2. 在页面右上角，单击“分支”。

3. 在“所有者”下，选择下拉菜单，然后单击分支存储库的所有者。

4. 默认情况下，分支的名称与其上游存储库的名称相同。 （可选）若要进一步区分分支，请在“存储库名称”字段中键入名称。

5. （可选）在“描述”字段中键入分支的描述。

6. （可选）选择“仅复制默认分支”。

   对于许多分支场景（例如参与开源项目），你只需复制默认分支。 如果未选择此选项，所有分支都将复制到新分支中。

7. 单击“创建分支”。

克隆项目的派生

现在，你的帐户下有 github/docs 仓库的派生，但需要将其复制到本地计算机才能开始处理更改。

1. 在 GitHub 上，导航到你的 github/docs 仓库派生****。

2. 在文件列表上方，单击 “代码”。

   

3. 复制存储库的 URL。

   • 要使用 HTTPS 克隆存储库，请在“HTTPS”下单击 。

   • 要使用 SSH 密钥克隆存储库，包括组织的 SSH 证书颁发机构颁发的证书，请单击“SSH”，然后单击 。

   • 要使用 GitHub CLI 克隆存储库，请单击“GitHub CLI”，然后单击 。

     

4. 在 Mac 或 Linux 上，打开终端。 在 Windows 上，打开 Git Bash。

5. 将当前的工作目录更改为您想要存储克隆目录的位置。

6. 键入 git clone，然后粘贴之前复制的 URL。 它将如下所示，使用你的 GitHub 用户名替换 YOUR-USERNAME：

   Shell

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

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

在主题分支中进行更改

现在可以进行更改了！ 开始之前，最好先在你的派生中创建一个主题分支，并为其指定一个描述性名称********。 使用主题分支可以让你的工作与仓库的默认分支分开。

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

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

• 使用 Copilot 提供代码建议，让你对自己的更改充满信心。
• 记录你的代码并编写测试。 这些内容经常被忽视，但助于确保合并你的贡献。
• 询问 Copilot 有关该议题的问题，以帮助你进一步了解实施要求。
• 使用 Copilot 来审查你的更改，以确保它们符合项目的编码风格和文档要求。
• 使用 Copilot 来帮助指导如何在本地计算机上生成和测试项目。

提交和推送更改

更改准备就绪后，可以在仓库中暂存并提交它们。 撰写提交消息时，请使用清晰、简洁的提交标题（少于 50 个字符），概括提交的作用。 尽可能将相关更改分组到单个提交中，但将不相关的更改保留在单独的提交中。

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

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

为了提高可读性，请尽量将提交描述行保持在 72 个字符以下。 完成提交本地更改并准备将其推送到 GitHub 时，请将更改推送到远程位置。

git push

git push

提交拉取请求

现在已将更改推送到 GitHub，可以打开拉取请求了。 即使尚未完成在分支中所做的更改，也可以打开拉取请求以供审查。 在贡献过程中尽早打开拉取请求可让维护者了解情况，并可让其提供有关更改的初始反馈。

1. 转到 GitHub 上的派生仓库。 例如，https://github.com/YOUR-USERNAME/docs。
2. 你应该会看到针对你最近推送的分支的“Compare & pull request”提示。 单击该选项。
3. 如果没有，请转到“Pull requests”选项卡并单击“New pull request”。
4. 确保基础仓库为 github/docs，且基础分支为其主分支（例如 main）****。
5. 确保头部仓库是你的派生 (YOUR-USERNAME/docs)，并且比较分支是你的分支****。
6. 为您的拉取请求输标题和说明。 在说明中引用拉取请求将关闭的议题。 例如，Closes: #15。 这会为拉取请求提供上下文，并在合并拉取请求后自动关闭议题。

与项目维护者合作

提交拉取请求后，下一步就是让项目维护者审查并提供反馈。 项目维护者可能会请求进行更改以匹配代码库的样式或体系结构，有时需要重构大量工作。

• 当收到有关拉取请求的反馈时，即使批评看起来很严厉，也要及时且专业地做出回应。 维护者通常关注代码质量。
• 如果请求对拉取请求进行更改，请不要打开新的拉取请求来处理更改。 使现有拉取请求保持打开状态并进行更改有助于防止维护者丢失上下文。
• 如果你的拉取请求数周仍未得到解决，请礼貌地跟进评论以请求反馈。 不要直接提及维护者的昵称****。 维护者经常在开放源代码工作与全职职责之间进行平衡，了解其时间约束可促进更好的协作。
• 如果你的贡献未被接受，请向维护者寻求反馈，以便在下次做出贡献时能够了解相关情况。

后续步骤

现在你知道了如何识别需要处理的正确议题、如何制定维护者想要合并的贡献以及如何浏览拉取请求审查流程。 GitHub 上的开放源代码社区已准备好迎接你独特的观点和技能。 找到让你兴奋的新项目，确定要处理的议题，然后开始做出贡献。