This guide is heavy on the mechanical side and misses a lot of important substantive parts, if your goal is to add value to an open source project.<p>Don't just create a fork, branch, and submit a PR without context. First, make sure the intent of your change is actually desired. Just because someone opened an Issue does not mean that it belongs in the project. Anyone in the world can open a Github Issue for any reason. Instead engage and discuss the Issue first and make sure it's actually something the project wants.<p>Don't just start writing code. Familiarize yourself with the codebase. This comes naturally if you are a user of the project, as you will naturally run into bugs or learn the software's behaviors and as you discuss the Issue or features with maintainers. There are far fewer right ways to build a feature than possible ways.<p>Finally, understand that your contribution is not "free" for the project. It takes time and consideration to even look at your PR and even more to code review it. The more popular the project, the more true this is.
There is one very important tip that's missing: Follow the original coding style <i>exactly</i>.<p>Not just spaces vs tabs or block styles, but idioms and other idiosyncrasies, too. Why? Imagine reading a source repo where every second block uses different bracket styles, mixing spaces with tabs and so on. It's going to look like a kludgy mess, and will be distracting to read.<p>There <i>is</i> no correct style for most languages (perhaps `go fmt` might be an exception), only opinions.
I dislike the idea of using 'origin' for my own remote name.<p>I keep 'origin' as the canonical remote and my local master branch tracks origin/master. I use people's usernames for their remotes (including for my own).<p>If I'm pushing a feature branch to my own remote:<p><pre><code> git push -u myusername mybranchname
</code></pre>
If I need to checkout someone's PR, it's:<p><pre><code> git remote add theirusername git@github.com:theirusername/repo.git
git fetch theirusername
git checkout -t theirusername/repo
</code></pre>
I've seen people at work who are new to git/Github struggle a lot with the 'origin'/'upstream' differentiation recently, especially when they're learning branching, and they don't seem to have any problems once I switch them over to using 'origin' + usernames.
I just want to emphasize that if reviewers ask you to make changes to your pull request, it is not a rejection or lack of appreciation. As the maintainer of an open source project, I greatly value contributors who will iterate and iterate until the change is accepted, and often, I will give them push rights ("collaborator" status) to pay it forward.<p>And if a change is rejected, it's usually because there was not enough discussion beforehand about how to solve the problem, the change itself did not undergo enough discussion/iterations, or the change is not really a solution to a problem. (It's not the maintainers saying "Go away and never come back" -- more like, "Thank you for your effort! Please approach this differently.")
If you'd like to avoid switching to the browser in your development workflow, I recommend checking out Git-Repo [0] that was posted to HN a little while ago [1].<p>Git-Repo basically tries to put as many steps of the contribution workflow in terminal as possible, by using the API of the git hosting services. It currently supports GitHub, GitLab, and Bitbucket.<p>[0]: <a href="https://github.com/guyzmo/git-repo" rel="nofollow">https://github.com/guyzmo/git-repo</a><p>[1]: <a href="https://news.ycombinator.com/item?id=12677870" rel="nofollow">https://news.ycombinator.com/item?id=12677870</a>
This is a great start!<p>Contributing can be a lot more than just PRs though:
- answering questions on stack overflow, chat (irc, gitter, slack)<p>- creating a minimal code repro, checking for duplicates, checking if a bug is fixed in a later release/master branch<p>- writing tutorials/usage scenarios, giving talks, just using the project and providing feedback<p>- helping with documentation + website<p>- translations if possible<p>- reviewing other PRs<p>- helping with the changelog, testing prereleases<p>- adding to the discussion on issues<p>Bigger projects can have a pretty hard time with maintenance: fixing bugs, juggling PRs, making releases, answering questions, etc.<p>(We're looking for help on <a href="https://github.com/babel/babel" rel="nofollow">https://github.com/babel/babel</a> and trying to figure out how we can make the project more contributor friendly!)
For many projects, Github is just a place to publish yet another public repo. Using github issues and pull requests is a sure fire way to feel ignored. If you want to contribute, e-mail the lead maintainer. Do not submit patches to the ether. Do not think anyone will look at your patches. Having started several large open source projects, and started / worked for a number of open source companies, I can tell you the best way to get involved is to work on your personal relationship with the other developers. If that means hanging out in IRC or Slack, that's what it takes. Github is a terrible form of communication, especially when your org / developers have 100+ repos.
Step 1: stumble upon a terrible bug (or that really obvious missing feature that _should_ be there) in your favorite library / framework / app.<p>Step 2: rant about it on HN / Github issues / whatever.<p>Step 3 (optional): try to reach developers on GitHub and get the obligatory "pull requests are welcome" response.<p>Step 4: In frustration, clone the repository, fix the damn bug and submit your pull request.<p>Steps 5..41: have an angry and emotional discussion with the devs who refuse to accept your PR because broken binary compatibility / regression tests / coding style / your choice of variable names etc. Fix all these issues and resubmit the PR until it's accepted.<p>Step 42: And this is how you become a contributor to high-profile projects like Docker, Akka, Spark etc, and now free to boast about it in your CV!
Of these, 1: Chose the project you want to contribute to (and 1.5: Choose the issue to work on) and 9: Follow up are the hard ones. Both are primarily social problems.<p>For 1, it's mostly about knowing yourself. What projects interest you, and where can you contribute?<p>For 9, it's convincing the owners that your contribution is a net positive. Start with 2: Check out how to contribute, and proactively reach out so your pull request doesn't come out of the blue.<p>Oh, and be willing to put your ego aside -- it can be tough to defend your work, particularly if you're a new (and thus haven't built up trust) contributor. It gets easier, both as the project learns to trust you and as you learn the work within their practices.
> The way people (usually) contribute to an open source project on GitHub is using pull requests.<p>I disagree with this premise. The way people usually contribute to an open source project on GitHub is creating an issue or adding to a discussion. IMHO this is more valuable than actually writing code because it helps other developers gauge the relative demand for a feature/bugfix and sometimes you find out that other people have already solved the problem in their own forks.
There are a few steps missing. Before the push, we need to pull on master and rebase the branch on top of master.
See triangular workflow in this page [<a href="https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows" rel="nofollow">https://github.com/blog/2042-git-2-5-including-multiple-work...</a>]
For anyone that is new to contributing to projects using git for version control I strongly recommend giving this tutorial a read: <a href="https://www.atlassian.com/git/tutorials/syncing" rel="nofollow">https://www.atlassian.com/git/tutorials/syncing</a><p>Additionally, the best way to learn git is to use it so try all the examples.
I can highly recommend hub [1], which does steps 3, 4, and 5 in one command:<p><pre><code> hub fork username/repo
</code></pre>
1: <a href="https://github.com/github/hub" rel="nofollow">https://github.com/github/hub</a>
I've been doing this without thinking about it for a while and after reading it from a beginner's perspective It seems like quite a few steps. It is the "right" thing to do though, as far as I know.
Why did this get so many upvotes? It's well written, but isn't it just a trivial guide on how to do a pull request? Not trying to be controversial, I'm just genuinely curious.
I would add "Make sure the maintainer of the repo will merge (or even look at) your PRs". I more than once had very reasonable PRs (bugfixes) waiting to be merged forever.
There is a lot of overlap with Github's own guide to Contributing to Open Source [1] and Forking Projects [2]:<p>[1] <a href="https://guides.github.com/activities/contributing-to-open-source/" rel="nofollow">https://guides.github.com/activities/contributing-to-open-so...</a>
[2] <a href="https://guides.github.com/activities/forking/" rel="nofollow">https://guides.github.com/activities/forking/</a>
It’s amazing that there aren’t many articles like this one. I wrote something very similar [1] last year because I simply couldn’t find a complete, step-by-step guide that addressed the details of forking, branching, etc.<p>[1] <a href="http://www.matiasz.com/2015/04/16/contribute-open-source-repository-github/" rel="nofollow">http://www.matiasz.com/2015/04/16/contribute-open-source-rep...</a>
Is there a breakdown of top projects by language? I'm a C# developer and would love to put my skills to work on an open source project, but how do I find one?
Here are some screencasts on this topic if that sort of thing interests you: <a href="https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github" rel="nofollow">https://egghead.io/courses/how-to-contribute-to-an-open-sour...</a>
> Hopefully some of the project mantainers will check your pull request and will give you feedback or notify you they decided to merge your changes soon.<p>Ah, my experience is that I'll submit a PR and it'll just be ignored until the end of time.
what if I want to start my contribution I just don't know which project to choose ? this assumes that I already know the project I want to contribute to.
<i>Shudder</i>. This embodies all that is wrong with open source development these days.<p>Horrible GitHub workflow: corporate logos, octop^Hcat, CoC shoved in your face on every commit.<p>I'm currently forced to contribute to a GitHub project, it is the most annoying, bureaucratic and brainwashing workflow I've ever experienced.