GitHub翻译之 ‘Contributing to Open Source’

Contributing to Open Source on 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.
  一种参与到开源项目中的最好办法是通过你现在正在用项目去贡献。GitHub 是5百多万个开源项目的家园。这些开源项目包含了像 recipes，HTML/CSS,* Ruby*,Astrophysics等众多技能的集合。这个指导说明涵盖了你可能寻找的所有的典型项目以及如何贡献一份自己的力量。

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.
我们建议你从一个你已经在用的开源项目（或者感兴趣的项目）。以下是一些资源的链接：
- GitHub Explore ： 现在非常流行的项目
- GitHub Stars: 由个人领导的著名项目
- GitHub Showcases: 一个发现相关开源源码的地方
- Designer News: 一些处于发展阶段的设计项目
like this :

A Typical Project(一个典型的项目)

Below are some elements you’re likely to come across in an open source project on GitHub.
  下面是你在了解一个开源项目的时候可能遇到的一些术语
1. 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.
每一个开源项目都会有一个社区，社区的成员会以正式的或非正式的角色进行自组织：
- Owner 是一个项目的创建者，可能是一个人，也可能是一个公司组织
- Maintainers and Collaborators 维护人员和合作人员是这个项目的主要开发维护人员，他们掌握着项目的开发方向进度等。项目的创建者和维护者往往是一个人。他们拥有对项目代码库写的权限。
- Contributors 贡献者是能够获取代码，修改后提交代码并提出合并请求的人员
- Community Members 社区成员是经常使用并且非常关心这个项目的人员，他们在新功能发布
和Pull Requests 中总是积极参与讨论。
2. 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.
  GitHub上几乎所有的项目都有一个 README.md 文件。这个readme文件详细描述了这个项目如何使用、编译，有些还说明如何向这个项目贡献代码。
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.
  项目和项目的维护人员是多种多样的，因此贡献的方式也是多种多样的。你要睁大眼睛去看那个带有CONTRIBUTING 标签的文档。贡献文档详细说明了一个开源项目的维护人员希望成员以何种方式提供程序补丁、新功能。
包含写什么样的测试方案、代码的语法风格、补丁程序应该集中在哪些地方等。
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.
   License 文件是一个项目的软件许可说明。一个开源的项目许可说明包含了规定程序使用者对程序的操作范围(例如：可以使用、修改、分发)，以及程序的贡献者允许其他人对自己修改的代码的使用范围。了解软件许可说明的途径有很多，你可以在 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.
   一个大型项目的使用说明远远超过了一个’readme’所能提供。在这种情况下，你会发现往往会有其它链接文件，或者在代码库中有名称为 ‘docs’的文件夹。
如下图所示：

Alternatively, the repository may instead use the GitHub wiki to break down documentation.
还有一种选择是用 GitHub wiki 的方式来分解众多的说明文档。

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
如果你发现你使用的项目中有一个bug(你不知道如何处理)，或者在看项目文档的时候遇到了难点，或者关于这个项目你有一个问题，那么就创建一个问题! 无论你提出什么样的问题都无所谓，不可能只有你一个人遇到这样的问题，别人也许会从你的问题中得到帮助。关于问题是如何起作用的，请查看我们的 问题指导

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.
 
- 检查你的问题在问题库中是否存在。提出重复的问题对于所有人而言都是无意义的，因此在打开的问题和已经关闭的问题中查询一下是否已经有与你相同的问题。
- 把你的问题写清楚：期望的结果是什么，使用过程中到底发生了什么？让别人如何重现问题的细节。
- 给出一个可以重现问题的demo
- 包含系统的详细信息，比如你用的是什么浏览器、文档库，你使用的是什么浏览器，以及它的版本。
- 把你的错误日志粘贴到相应的问题下面，并用三个重音符 ``` 包括起来。

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.
   如果你能够为bug 打补丁，或者自己开发新的功能——那再好不过了，利用写好的代码创建一个 “Pull Request” !确保你已经认真阅读了关于“贡献”的相关文档，理解了软件许可中要求的，必要的话得有一个 CLA的签名。一旦你提交了一个合并请求，项目的维护人员会比较你修改后的分支与当前生产的分支，最终决定是否要把你修改的代码整合到当前生产中。
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.
把GitHub中你需要的代码库复制到你本地。修改代码后通过’upstream’把你代码上传到服务器，你要经常做，这样就不容易与其他人代码起冲突。
-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.
如果你修改了 HTML/CSS 文件，那么请把截屏图片放到 ‘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.
  一旦你打开了一个“pull request”,围绕你的提议会展开一场讨论。其他贡献者或者使用者会参与进来共同讨论，但最终的决定由维护者作出决定。你会被要求针对你的Pull Request 作出一些修改，这样的话，就会在你的分支上产生更多的提交，它们会自动合并到已经存在的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.
    如果你修改的代码最终被合并到主程序中——太好了！如果没有，没有问题，它也许并不是项目维护人员想要的，或者也许他们已经在开发这个功能了。就是这些了，我们的建议是你带上已经得到的反馈信息继前进，继续提出”Pull Request” ——或者创建属于你自己的开源项目。That’s all!