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.