如何参与一个GitHub开源项目

Posted 2020-08-11 白乾涛

Github作为开源项目的著名托管地，可谓无人不知，越来越多的个人和公司纷纷加入到Github的大家族里来，为开源尽一份绵薄之力。对于个人来讲，你把自己的项目托管到Github上并不表示你参与了Github开源项目，只能说你开源了自己的项目，可以任别人自由下载。

那么该如何参与Github的开源项目呢？为此，Github官方团队曾经写了一篇很棒的文章 Contributing to Open Source on GitHub，专业指导大家如何参与Github的开源项目。 下面是原文及翻译。

---

原文路径：https://guides.github.com/activities/contributing-to-open-source/

A great way to get involved in参与 open source is to contribute to the existing projects you’re using. GitHub is home to more than 5 million open source projects. There are projects for every skill set各个领域 like recipes, HTML/CSS, Ruby, Astrophysics and many more. This guide will cover涵盖 what you might find in a typical project and how to make a great contribution.

Find Projects

We recommend推荐 that you start by finding a project that you’re already (or are interested in) using. Here are a few great places to look:

• GitHub Explore: Popular and trending热门 projects.
• GitHub Stars: Projects starred by other people.
• GitHub Showcases: A way to discover related repositories.相关库
• Designer News: Front-end development and design projects.

A Typical Project

Below are some elements you’re likely to come across遇到 in an open source project on GitHub.

The Community社区

Projects often have a community around them, made up of组成 other users in different (formal or informal) roles:

• Owner is the user or organization that created the project has the project on their account.
• Maintainers维护者 and Collaborators协作者 are the users primarily doing the work on a project and driving the direction驾驶方向. Oftentimes the owner and the maintainer are the same. They have write access权限 to the repository.
• Contributors贡献者 is everyone who has had a pull request merged合并 into a project.
• Community Members are the users who often use and care deeply about the project and are active活跃 in discussions for features and pull requests.

The Docs

The what’s-what of common files in projects.

Readme

Nearly all GitHub projects include a README.md file. The readme provides a lay of the land for a project with details细节 on how to use, build and sometimes contribute to a project.

Contributing

Projects and project maintainers vary不同, so the best way to contribute will also vary. Keep your eye open for a doc labeled标注 CONTRIBUTING. Contributing docs detail the specifics about how a project’s maintainer would like to see patches补丁 or features功能 contributed. This can include what tests to write, code syntax语法 style or areas to focus on for patches.

License许可

A LICENSE file, well, is the license for the project. An open source project’s license informs users what they can and can’t do (e.g., use, modify, redistribute重新发布), and contributors, what they are allowing others to do. There are many ways to license and open source project, you can read more about what each license means at choosealicense.com.

Documentation and Wikis

Many larger projects go beyond不止 a readme to give instructions指导 for how people can use their project. In such cases you’ll often find a link to another file or a folder named ‘docs’ in the repository.

Alternatively另外, the repository may instead代替 use the GitHub wiki to break down documentation.

Contributing to a Project

Now that you’ve found the material资料 for understanding the project, here is how you can take action.

Create an Issue话题

If you find a bug in a project you’re using (and you don’t know how to fix it), have trouble following the documentation or have a question about the project – create an issue! There’s nothing to it很简单 and whatever issue you’re having, you’re likely not the only one, so others will find your issue helpful, too. For more information on how issues work, check out our Issues guide.

Issues Pro Tips专业提示

• Check existing issues for your issue. Duplicating重复 an issue is slower for both parties so search through open and closed issues to see if what you’re running into has been addressed解决 already.
• Be clear about what your problem is: what was the expected outcome, what happened instead? Detail how someone else can recreate the problem.
• Link链接 to demos recreating the problem on things like JSFiddle or CodePen.
• Include system details like what the browser, library or operating system you’re using and its version.
• Paste error output or logs in your issue or in a Gist. If pasting them in the issue, wrap包裹 it in three backticks: ` ``` ` so that it renders呈现 nicely.

Pull Request

If you’re able to patch修复 the bug or add the feature yourself – fantastic太棒了, make a pull request with the code! Be sure you’ve read any documents on contributing, understand the license and have signed a Contributor Licence Agreement (CLA) if required. Once you’ve submitted提交 a pull request the maintainer(s) can compare比较 your branch to the existing one and decide whether or not to incorporate合并 (pull in) your changes.

Pull Request Pro Tips

• Fork the repository and clone it locally. Connect your local to the original原始的 ‘upstream’ repository by adding it as a remote远程. Pull in changes from ‘upstream’ often经常 so that you stay up保持 to date so that when you submit your pull request, merge conflicts合并冲突 will be less likely. See more detailed instructions here.
• Create a branch for your edits.
• Be clear about what problem is occurring出现 and how someone can recreate that problem or why your feature will help. Then be equally同样 as clear about the steps步骤 you took to make your changes.
• It’s best to test. Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don’t break破坏 the existing project.
• Include screenshots of the before and after if your changes include differences in html/CSS. Drag and drop拖放 the images into the body of your pull request.
• Contribute in the style of the project to the best of your abilities尽你所能. This may mean using indents缩进, semi colons分号 or comments注释 differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain维护 in the future.

Open Pull Requests

Once you’ve opened a pull request, a discussion will start, around your proposed changes. Other contributors and users may chime in参与, but ultimately最终 the decision is made by the maintainer(s). You may be asked to make some changes to your pull request, if so, add more commits to your branch and push them – they’ll automatically go into the existing pull request.

If your pull request is merged – great! If it is not, no sweat没什么大不了的, it may not be what the project maintainer had in mind所期望的, or they were already working on it. This happens, so our recommendation建议 is to take any feedback you’ve received and go forth继续努力 and pull request again – or create your own open source project.

---

参与开源项目的最佳办法就是加入到你正在使用的已有项目上来。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出去— 或者创建你自己的开源项目。

来自为知笔记(Wiz)