如何参与一个 GitHub 开源项目？

最近一年开源项目特别的热，很多技术大会或论坛都以开源项目作为主题进行探讨，可见这是一种趋势。而Github作为开源项目的著名托管地，可谓无人不知，越来越多的个人和公司纷纷加入到Github的大家族里来，为开源尽一份绵薄之力。对于个人来讲，你把自己的项目托管到Github上并不表示你参与了Github开源项目，只能说你开源了自己的项目，可以任别人自由下载。那么该如何参与Github的开源项目呢？相信很多人都有这方面的疑问，网上也有一些参差不齐的教程教大家如何“pull request”、如何“commit”等等。但这些教程往往不够全面或不够完全正确，搞不好可能让你陷入一个误区。鉴于此，前几天Github官方团队写了一篇很棒的文章Contributing to Open Source on GitHub，专业指导大家如何参与Github的开源项目。作为Github的入门级粉丝，将这篇教程翻译出来，供那些对开源项目刚兴趣的人参考借鉴。

 

下面是正文。我的Github地址：https://github.com/lanxuezaipiao，有自己的项目也有fork的非常优秀的编程资料、编程笔记和计算机优秀论文资料，有兴趣的可以fork下。

 

参与开源项目的最佳办法就是加入到你正在使用的已有项目上来。Github上有500多万开源项目，涉及到各个领域的技术，像recipes,HTML/CSS,Ruby, Astrophysics等等。该指南将涵盖你在一个典型的项目中可能出现的事情以及如何为开源项目作出贡献。

 

 

找项目

我们推荐你从已正在使用的或感兴趣的项目开始。这里有几个很棒的地方供你参考：

 

 

• GitHub Explore:  受欢迎和热门的项目。
• GitHub Stars:  被其他人star过的项目（指的是你自己库的项目）。
• GitHub Showcases:  一个能搜索相关库的方法。
• LayerVault News:  .前端和设计相关的项目。

 

 

 

一个典型的项目

下面是一些你在Github开源项目中可能遇到的因素。

 

 

The Community（社区）

 

项目通常会有一个社区维护，由不同角色（正规或非正规）的其他用户组成：

 

• 所有者（Owner）：即创建该项目且在他们Github账户上有该项目的用户或组织。
• 维护者和协作者（Maintainers and Collaborators）： 致力于一个项目并促进该项目发展的用户。通常所有者和维护者是同一个用户或组织，他们对项目库都有写的权限。
• 贡献者（Contributors）：每一个对该项目发出过pull request并合并到项目中的用户都是贡献者。
• 社区成员（Community Members）：即那些经常使用且非常关心该项目的用户，他们在讨论功能特征和pull request上非常活跃。

 

 

 

The Docs（文档）

一般项目中都有的文件。

 

 

Readme

几乎所有的Github项目都包含一个README.md 文件。readme提供了该项目的一个概览及关于如何使用、构建甚至如何贡献于一个项目的相关细节。

 

 

Contributing

项目和项目维护者不同，所以每个项目所期望的作贡献的最佳方法也会有所不同。一定要注意一个标注为CONTRIBUTING的文档，Contributing文档详细描述了一个项目的维护者希望看到贡献的补丁或功能应该符合怎样的规格。这可能包含要写什么测试，代码语法规范或补丁集中的区域。

 

 

License

 

一个LICENSE文件当然就是该项目的许可证了。一个开源项目的license会告诉用户他们能做和不能做的（例如使用、修改、重新发布），及告诉贡献者他们允许其他人做的。有许多的办法对开源项目加上许可证，你可以在choosealicense.com读到更多的关于每个许可证的含义。

 

Documentation and Wikis

许多大型项目有的不只有一个readme来指导人么如何使用他们的项目。在这种情况下你通常能够发现一个指向库中名为“docs”的另一个文件或文件夹的链接。

 

 

另外，该库也可能使用Github wiki来代替文档。

 

 

贡献于一个项目

既然你已经找到了理解该项目的相关资料，下面你就可以采取一些行动了。

 

 

建立一个话题

如果你发现了你正在使用的项目中的一个bug（但是你不知道怎么去修复它），或对文档有不解或对项目有疑问 — 那么创建一个话题吧！这非常容易且一般你不管创建什么话题，你都可能不是唯一一个出现该问题的人，所以其他人可能会发现你的话题很有帮助。关于更多的话题介绍，请查看我们的Issues guide。

 

 

话题专业提示

• 在建话题之前检查已有的话题：话题重复对双方都无利，所以搜索整个正开放和已关闭的话题以检查你遇到的问题是否已经有人解决了。
• 务必对自己的问题有清晰的认识：期望的结果是什么？然而却发生了什么？ 详细描述其他人如何重现该问题。
• 在像JSFiddle 或CodePen类似的平台上重现该问题并给出问题demo的链接。
• 包含一些系统相关的细节，比如用的什么浏览器、库或操作系统及版本号。
• 在你的话题或在Gist里贴出你的错误输出或日志。如果在话题里贴出来，请用三个反引号``` 包围起来使得能够良好的呈现给大家。

 

 

 

Pull Request

如果你能够修复bug或自己添加功能 — 太棒了，请发一个pull request 吧！确保你已经读过任何关于contributing的文档，且需要理解license以及已经签过CLA（如果需要的话）。一旦你提交了一个pull request，维护者就会将你的分支与已有的分支作比较来决定是否要合并（即pull in）你作的改动。

 

 

Pull Request专业提示

• Fork 该项目库及将它clone到本地。通过添加为远程的方式在本地连接到原来的‘upstream’库。经常从‘upstream’库pull in改动以保持库最新，这样当你提交pull request时，就不大可能发生合并冲突了。点这里看更多的指导细节。
• 为你的编辑单独建立一个分支 。
• 务必清楚所出现的问题以及如何重现该问题或为什么你的功能有帮助。然后同样的要清楚做一些改变有哪些步骤。
• 最好测试一下。在任何已有的测试（如果存在）上运行你所做的改动并在必要时创建新的测试。不管测试存不存在，都要确保你的改动不会破坏已有的项目。
• 如果你的改动包含了HTML/CSS方面的不同，那么请包含改动前和改动后的截图。将你的图片拖放到你pull request的正文里。
• 尽你所能的在项目的风格上多做努力。这可能意味着使用不同于你自己Github库中采用的缩进，分号或注释，但是这让维护者更容易合并，也让其他人更容易理解和以后的维护。

 

 

开放的Pull Requests

一旦你打开一个pull request，就会有一个讨论，围绕你提出的改变作出探讨。其他的贡献者和用户可能会参与进来，但最终由维护者做决定。你可能会被要求对你的pull request做一些改变，如果这样，请给你的分支添加更多的commit并push它们 — 它们将自动的加入到已有的pull request里。

 

 

如果你的pull request被合并了 — 太好了！如果没被合并的话，也没什么大不了的，也许这不是项目维护者所期望看到的改动，亦或者他们已经致力于该bug或功能。这种情况有可能发生，所以我们的建议是：对收到的结果做出反馈，进一步努力然后再次pull request出去— 或者创建你自己的开源项目。

 

翻译自：Contributing to Open Source on GitHub