参与开源的一个好方式是为当前你正在使用的(开源)项目贡献力量。Github为多达五百万的开源项目提供托管。这里有各种技术集的项目,比如:recipes、 HTML/CSS、Ruby、Astrophysics和其他许多项目。这份指南会涵盖在一个典型项目中的各个方面,同时指导如何参与贡献。
查找项目
我们建议你开始时查找你已经在使用的项目(或者感兴趣的项目)。下面是一些值得访问的链接:
- · GitHub Explore: 当前热门项目和有潜力的项目.
- · GitHub Stars: 项目由他人评价的排行榜.
- · GitHub Showcases: 查找相关的仓库.
- · LayerVault News: 前端和设计项目.
一个典型的项目
下面是在一个开源项目中可能会访问的一些元素。
社区
项目通常都含有一个围绕它的社区,由其他不同角色用户创建:
- 所有者是项目创建者或其组织,该账户身份拥有这个项目。
- 维护者和协作者是一个项目的主要开发者和负责驾驭项目开发方向的人。通常项目所有者和维护者是同一个人。他们拥有仓库的写权限。
- 贡献者是指任何对项目进行pull操作并合并到项目中的人。
- 社区成员是经常使用项目的用户,深切关心项目并且活跃讨论项目的特性和pull请求。
文档
项目中包含的通用文档文件
请读我(Readme)
几乎所有Github上的项目都包含一个README.md文件。这个Readme描绘了项目使用、编译,有些时候也提供项目参与的详细地图。
参与文档(Contributing)
不同项目和项目的维护人员存在差异,所以参与项目的方式也不同。你可以关注一个叫CONTRIBUTING的文档。参与文档详细描述了项目维护人员希望看到补丁和贡献特性的规范。这可能包含了如何编写测试,代码风格或者补丁应用范围。
许可证(License)
LICENSE文件是项目的许可证说明文件。一个开源项目的许可证告诉用户他们可以做和不可以做什么(例如:使用,修改和分发),以及参与者的权利,这个文件告诉其他人他们可以怎么做。许可和发布开源项目有许多方式,你可以在这个网站了解不同许可的含义:choosealicense.com.
文档和wiki
许多大型项目略过Readme来指定用户如何使用其项目,这种情况下你在仓库中通常会找到一个链接或者一个名叫“docs”的文件夹。
另外,仓库也可以使用Github的wiki系统来代替文档。
参与一个项目
现在你已经找到理解一个项目的材料了,开始行动起来吧。
创建一个Issue
如果你发现你使用项目中的一个bug(但是你不知道如何去修复它),在文档中也找不到相关信息或者对项目存有疑问——创建一个issue!不管你的issue什么内容或者你现在有什么issue,你可能不是唯一存有疑问的,其他用户可能会从你的issue得到帮助。此外,想要更多关于issue如何工作的信息,请查看我们的issue指南。
Issues专业建议
- 检查当前的issue是否有与你相关联的。发布重复的issue会让双方都降低效率,搜索开放和已经关闭的issue来检查你现在提出的issue是否已经被提及。
- 请明确你的问题:期望的输出是什么,实际发生了什么?以及其他人如何复现你的问题。
- 对示例的链接:复现问题的方式,比如提供在jsfiddle和codepen上的示例链接。
- 汇报系统环境的详细信息。比如使用什么浏览器,使用的库或者操作系统的版本。
- 在你的issue或者Gist中粘贴错误输出或者日志。如果你粘贴错误输出或日志到一个issue中,请使用三个反引号```使得显示更漂亮。
Pull请求
如果你自己有能力修复bug或者添加新特性——那就太妙了。对代码基做一个pull请求!请确保你已经读过参与相关的文档了,了解许可证并拥有一个签名的CLA(如果需要的话)。一旦你提交了一个pull请求,项目的维护人员可以比较你的分支和当前分支来决定是否合并(pull in)你的变更.
Pull请求专业建议
- Fork仓库并克隆到本地。通过连接你本地到初始的“上游”仓库并标记作为一个远程连接。时常从“上游”Pull in变更保证在提交你的pull请求时是最新版本,从而减少合并冲突的可能性。详细的指导见这里。
- 为你的编辑创建一个分支。
- 清楚问题是如何发生的,同时其他人如何去复现问题,或者你提交的特性是有帮助的。同样的,清楚了解你的变更执行步骤。
- 最好进行测试。如果有,对已有的测试项目测试你的变更,需要时创建一个新的测试。不管测试是否存在,请保证你的变更不会扰乱现有项目。
- 提供你变更前后的截图,包括在html/css上的不同,拖拽图片到你的pull请求中。
- 尽量参照项目风格来参与项目。这包括使用缩进,符号和注释,也许在你的项目中使用有所不同,不过使用(和项目一致的风格)会让项目维护人员更容易合并,其他人也更容易理解和在将来进行维护。
打开pull请求
一旦你打开了一个pull请求,一个你提交变更相关的讨论就会开始。其他参与者和用户会参与进来。但是最终还是由维护者进行决策。你可能会被要求对你的pull请求进行修改,如果是这样,为你的分支添加更多的注释并push它们——它们会自动加入已经存在的pull请求。
如果你的pull请求被合并了——非常棒!如果没有,也没问题,可能项目的维护者并没有注意到,或者他们已经为此做了一些事情。这时,我们建议你接受你收到的反馈并继续处理,再次提交pull请求——或者创建你自己的开源项目。