如何为开源项目做出贡献——你应该知道的非技术性的事情

我已经为开源项目贡献了几年，并从中学习到了很多东西。这些经验让我更近距离地观察开源流程，从技术方面(如 Git 和 GitHub)到非技术方面。

尽管非技术方面和技术方面同样重要，但它们往往被忽视。在本文中，我将分享在为开源项目做贡献时，你应该知道的非技术方面的重要事情。

1、存储库中有哪些重要的文件？

在这一节中，我们将讨论在为开源项目做贡献时可能遇到的一些重要文件。

1.1 README.md 文件

当你有兴趣为一个开源项目做出贡献时，你应该经常阅读 README.md 文件（通常称为 README），以熟悉该项目。

README.md 文件是项目的门面，包含所有必要内容。在 README 中，你通常可以找到大部分（如果不是全部）这些部分：

• 项目的描述。
• 项目所用的技术。
• 有关如何安装、运行和使用项目的说明。
• 项目的许可证。
• 行为准则。
• 如何为项目做出贡献。
• 期望的沟通风格(通过问题和拉取请求评论、GitHub 讨论、聊天服务应用程序，如 Slack 或 Discord 等)。

1.2 CONTRIBUTING.md 文件

其次，您必须了解为项目做出贡献所应遵守的规则。不同项目的贡献程序和要求可能不同。例如，在某些项目中，您需要在问题分配给您之前对其发表评论，而其他项目则允许您将问题分配给自己。

CONTRIBUTING.md 文件作为贡献指南，解释了社区的规则和对贡献者的期望，从创建问题到创建 pull request。

在大多数情况下，你可以在 README 中找到一个贡献部分，但如果 README 中没有包含，你可以在名为 CONTRIBUTING.md 或类似的文件中找到它。

1.3 LICENSE 文件

您不能仅仅假设 GitHub 上的所有项目都是开源的，并且它们的代码库都是免费提供的。

“在大多数司法管辖区，任何代码或内容都自动由作者拥有版权，除非另有说明，否则所有权利均归作者所有。”(来源：开源许可证：什么、哪些和为什么)

“All rights reserved”意味着除非所有者允许，否则任何人不得使用、修改或重新发布项目中的任何内容。如果你忽略它，他们可以合法起诉你。因此，GitHub 上的项目只有在许可证中明确规定的情况下才算是开源的。

你通常可以在 README 文件的“About”部分找到许可章节，它位于一个名为 LICENSE 的文件中。

1.4 CODE_OF_CONDUCT.md 文件

您应习惯性地阅读社区的《行为准则》（COC）。COC 是社区的内部规则。它存在的理由是：为贡献者维护一个安全、温馨的空间。遵守 COC 可以防止您被社区和项目禁止。

你可以在库的“About”部分找到名为 CODE_OF_CONDUCT.md 的文件，大多数时候，它也包含在 README 和贡献指南中。

2、开源中的道德规范

2.1 检查是否有重复

假设你在本地机器上安装并运行了一个项目，然后遇到了一个 bug，或者你通读了文档，发现缺少了一个步骤，你可能想要发起一个 issue 来解决它。

在这样做之前，你必须检查是否已经提出了类似的(开放和关闭)问题或 PR 请求，以避免重复。在 GitHub 上的问题或 PR 请求页面顶部的搜索栏中输入可能的关键词，以检查可能的重复。

例如：使用“docs”关键字搜索未解决的问题

is:issue is:open docs

搜索带有“button”关键字的已关闭的 pull 请求

is:pull request is:closed button

检查重复将有助于防止您的问题或 pull 请求被维护者拒绝。

2.2 在处理 Issue 之前征求许可

开源中的基本原则之一是，除非贡献指南中另有说明，否则在处理某个问题时要先征得维护者的同意。征得同意可以帮助维护者控制和避免重复的 pull 请求。

你只想在得到维护者的绿灯后进行更改并创建 pull request。如果你忽略了这部分内容并继续进行更改，你的 pull request 可能会被忽略或拒绝。这是因为这个问题可能已经分配给其他人了，或者这个问题当时可能不是他们的优先事项。

不管怎样，这对你来说都是一种损失。那么，在请求许可时应该做什么呢？

1）检查问题是否已经分配

当你在 GitHub 仓库中打开 issue 标签时，或者当你打开 issue 时，你可以通过查看“Assignee”列来查看问题是否已经被分配。

2）查看评论线程

您还需要确保没有人要求维护者将问题分配给他们。如果他们没有得到任何回复，那么维护者可能还没有看到这条评论。您还应该查看线程中的其他信息，以进一步了解该问题。

3）请留言申请您希望解决的问题

你可以说：“你好，我想处理这个问题。你能分配给我吗？”或者“我看到这个问题已经分配了，但我好久没有看到任何进展了。如果你仍然需要帮助，我可以处理这个吗？”

4）等待维护人员回复您的消息

如果他们(维护者)说你可以拥有它并分配给你，那么你可以开始处理这个问题，最后创建一个 pull request。

3、什么是良好优先问题标签(good-first-issue)？

GitHub 上的标签是传递问题或 pull request 类型或状态信息的标签。 good-first-issue 是项目所有者和维护者认为适合初学者使用的标签。

我曾经创建了一个关于链接断裂的问题，我解释了这个错误以及贡献者必须采取的解决步骤。

我还提到这个问题是新手友好的，所以我们想把它留给那些希望为项目做出贡献的新手。在通过维护者的审查后，这个问题被标记为 good-first-issue。

可悲的是，那些故意挑起这个 issue 的人并不是新手。

如果您已有一定的经验，请考虑离开此标签。该标签适用于开源或项目所用技术的初学者。

4、良好的沟通和耐心

与维护者和其他贡献者交流时，请务必使用清晰礼貌的语言。请记住，非同步交流容易造成翻译上的损失和交流上的误解。

如果你需要对某事进行更明确的说明，请询问维护者。不要做假设。你可以在 issue 或 pull request 评论中提问。一些社区也有 GitHub 讨论板，你可以在顶部栏找到，而一些人则使用 Slack 或 Discord 等聊天服务应用程序来分享想法、提问或澄清。

维护者可能会要求您修正 pull request 中的某些内容，或者用一句简单明了的话来要求您说明。简短而直接的消息大多是因为他们很忙。他们必须快速有效地回复信息。不要针对个人，因为这可能会导致沟通不畅，甚至失去作出贡献的机会。

开源社区的大部分维护者和贡献者都是志愿者。也就是说，他们有自己的生活和项目之外的其他职责。所以，当你贡献代码时，你需要有耐心。不要要求维护者立即回答你的问题或合并你的 pull request。

5、以结构化的方式编写 Issue 和 PR

一些开源社区在 GitHub 上提供模板来打开一个 issue 或创建一个 pull request。但是当他们不提供的时候，考虑以结构化的方式来编写它们。这将方便每个人看到细节，并帮助维护者审查和合并 pull request。

5.1 如何写 GitHub Issue

在写 Issue 时，需要考虑以下几点：

• 使用清晰和描述性的标题：通过阅读一个清晰和描述性的标题，每个人都可以理解问题。例如，“修复：链接到关于页面导致 404 错误”。
• 搜索类似问题：检查开放和关闭的问题，看看是否有与您的问题类似或相同的问题。如果您没有找到任何类似的问题，那么在描述中说明您已经检查过了，没有找到任何类似的问题。这一步对于避免任何重复是至关重要的。
• 问题描述：尽可能直接地描述问题。
• 预期行为：描述问题的预期行为。
• 实际行为：陈述导致问题的实际问题行为。
• 重现问题：我们需要采取哪些步骤来重现问题？这将有助于每个人运行相同的步骤并进行测试。下面是一个例子：

1. Go to this link.
2. Click this button.
3. This is what is happening.

• 截图或屏幕录像：如果有必要，提供一些截图或屏幕录像。这通常对 UI 问题有帮助。
• 提出解决方案：如果你有一个解决方案，你可以提出建议。但是如果你没有，也没关系。在你提出问题的时候，并不需要有一个解决方案。

下面是一个例子，它使用了上面列出的要点：

<!-- Issue 标题 -->
# fix: 关于页面的链接指向 404

<!-- Issue 内容 -->
## 描述

当我进入“关于”页面时，我得到了 404。

我搜索过，没有发现类似的问题。

## 预期行为

当我们进入“关于”页面时，我们应该看到“关于”部分。

## 实际行为

当我们进入“关于”页面时，我们会看到一个 404 页面。

## 如何重现

1. 访问 https://website.com。
2. 单击 "关于 "选项卡。
3. 您会看到 404。

## 截图

![404 in about page](link to the image)

## 建议

修复并使用正确的“关于”页面链接。

5.2 如何写 Pull Request（PR）

下面是写 pull request 时需要考虑的一些事情：

• 使用一个简短、清晰、信息丰富的标题：例如，“修复：链接到关于页面”。
• 使用一个清晰的修复描述：例如，“这个 pull request 修复了之前导致 404 错误的关于页面的链接。”
• 相关问题的链接：包括相关问题的链接，例如“Fixes #123”。
• 截图或屏幕录像：如果有必要，提供一些显示修复前后问题的截图或屏幕录像。

下面是一个使用上述结构的例子：

<!-- PR 标题 -->
# 修复：链接到“关于”页面

<!-- PR 内容 -->
## 相关问题

Fixes #123

## 描述

此 PR 修复了之前导致 404 的“关于”页面的链接。

## 截图

### 之前

![404 in about page](link to the image)

### 之后

![About page](link to the image)

6、值得一提的是：为开源做出贡献并不全是代码

我经常听到人们，特别是初学者，因为他们需要更多的技能或时间来帮助编码，而犹豫是否要为开源项目做贡献。

有很多非技术性的方式可以为项目和社区做出贡献，例如：

• 当你发现一个错误或有改进的余地时，就可以提出问题。
• 审查 issue 和 pull 请求。
• 改进项目的文档。
• 回答问题。
• 围绕项目提出想法。
• 招募新的贡献者。
• 指导其他贡献者。
• 写一篇博客文章或制作一个关于项目的视频。
• 在社交媒体上推广项目，等等！

End

为开源项目做贡献不仅仅是理解 Git 和 GitHub，一些非技术性的东西也需要你知道，希望这篇文章能有所帮助。