
How to contribute to an open source project on GitHub - vivaladav
http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/
======
jhchen
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.

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.

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.

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.

~~~
notyourwork
To sum all that in a nutshell: Collaborate.

~~~
delish
I'm curious to see what others think about your comment, notyourwork. To me
(maybe only me!) it looks like you're putting a pithy stamp on what the GP
said. Going a little farther, it looks to me like you're taking credit for
what the GP said. I do not see the value of saying, "To sum all that in a
nutshell: Collaborate." I see a value in what the GP said.

That said, this is the first time I've criticized this kind of comment. I've
seen people pithily-sum-up others a lot. If others disagree with me, I'll take
that into account.

~~~
kahrkunne
Your 2 paragraph criticism of one a one sentence comment is way more obnoxious
and contributes less.

What he was trying to do is summarize and give a one word interpretation/other
way of looking at it, not trying to do something insidious and inane as trying
to steal credit for an HN comment.

Sometimes it helps to have a point summed up in the briefest possible way.
What never helps, though, is posting inane accusations of ulterior motives to
HN comments.

~~~
pitay
I have to agree with delish on this matter. Notyourwork's comment actually
took away from the conversation. jhchen's assertions of, "be familiar with the
project", "don't just start writingcode", and "your contribution is not free
for the project" is not summed up nicely with the word "collaborate". To some
people, collaborate might mean to put in a pull request without caring whether
it is wanted or not, the exact opposite of what the OP said. "Collaborate" can
be taken in so many ways that it is useless, and in this instance actually
takes away from the message.

A closer summary of what the OP said is "Don't waste the project maintainers
time" which, while much better than "collaborate", is still a waste of time
and misses the specific advice the OP gives.

Delish is justified in calling out notyourwork's comment for providing nothing
useful. If I wrote a comment like the one notyourwork wrote I would be feeling
guilty for writing a comment just for points. Also the size of a comment is
not a good basis for criticism.

------
csl
There is one very important tip that's missing: Follow the original coding
style _exactly_.

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.

There _is_ no correct style for most languages (perhaps `go fmt` might be an
exception), only opinions.

~~~
the8472
> Follow the original coding style exactly.

Personally I would take any formatting and just run an auto-formatter over the
code section when I work on it the next time in case it bothers me.

Correct and sane code are far more important than hassling someone else to
conform to a particular style.

In my opinion applying styles is a task for machines, not humans.

~~~
Arnt
It's more than that.

I've had a patch rejected because my unit tests used the wrong verification
manner (java assertTrue() instead of assertThat() in cases where the latter
would report better error messages were the test to fail, as I recall).
Automatic blah will never catch this kind of thing.

Ditto for human-readable messages that have/lack full stops at the end.

Ditto for if() foo vs if() { foo } and the ever-lovely style question, are
abbreviations such as TCP to be called TCP or Tcp in camelcased identifiers?

Style is largely a human matter.

~~~
the8472
> Ditto for if() foo vs if() { foo }

At least that one can be fixed automatically by eclipse.

But sure, there are some things that are difficult to automate. What I'm
saying that one should not hassle a contributor over all those things that
that can be done by machines.

~~~
vsl
How is that "hassle"? Somebody needs to fix it, why should it be the
maintainer?

In my experience, not even bothering with style is a good indicator of
careless "shotgun coding" and such PRs typically have far worse issues. It's
also typical that such PRs won't have real issues fixed either.

~~~
the8472
> why should it be the maintainer?

I'm saying: Why should it be either human?

> In my experience, [...]

That seems fairly dismissive to me. An expert in a certain area can certainly
fix smaller issues with a few lines of code but only have a limited amount of
time on their hands. Having to read a lengthy style guide and making sure they
adhere to every single rule, especially when those rules are the opposite of
their regular habits, is a non-zero hurdle to contributing.

Offloading that work to a machine as far as possible lowers the burden to only
those rules that cannot be applied automatically.

------
brobinson
I dislike the idea of using 'origin' for my own remote name.

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).

If I'm pushing a feature branch to my own remote:

    
    
        git push -u myusername mybranchname
    

If I need to checkout someone's PR, it's:

    
    
        git remote add theirusername git@github.com:theirusername/repo.git
        git fetch theirusername
        git checkout -t theirusername/repo
    

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.

~~~
rcfox
FYI: GitHub will create a branch in your repo for pull requests. You shouldn't
need to pull directly from someone else's repo just to look at their pull
request.

[http://stackoverflow.com/a/30584951](http://stackoverflow.com/a/30584951)

~~~
brobinson
Didn't know you could pull by ID! Thanks!

------
mholt
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.

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.")

------
aban
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].

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.

[0]: [https://github.com/guyzmo/git-repo](https://github.com/guyzmo/git-repo)

[1]:
[https://news.ycombinator.com/item?id=12677870](https://news.ycombinator.com/item?id=12677870)

------
hzoo
This is a great start!

Contributing can be a lot more than just PRs though: \- answering questions on
stack overflow, chat (irc, gitter, slack)

\- creating a minimal code repro, checking for duplicates, checking if a bug
is fixed in a later release/master branch

\- writing tutorials/usage scenarios, giving talks, just using the project and
providing feedback

\- helping with documentation + website

\- translations if possible

\- reviewing other PRs

\- helping with the changelog, testing prereleases

\- adding to the discussion on issues

Bigger projects can have a pretty hard time with maintenance: fixing bugs,
juggling PRs, making releases, answering questions, etc.

(We're looking for help on
[https://github.com/babel/babel](https://github.com/babel/babel) and trying to
figure out how we can make the project more contributor friendly!)

~~~
Mz
_helping with documentation + website_

I am not a programmer. I do copywriting for pay and I have run a bunch of
different personal websites over the years (15+ years, I think). I know a
little HTML and CSS.

I am interested in getting involved in open source via first working on
copywriting and website stuff, since that is what I already have a background
in. I am finding it extremely opaque to figure out how on earth to do that.

I left a couple of related comments on HN recently:

[https://news.ycombinator.com/item?id=12860294](https://news.ycombinator.com/item?id=12860294)

[https://news.ycombinator.com/item?id=12851361](https://news.ycombinator.com/item?id=12851361)

I do have a github account and I recently went through the Hello World on how
to do pull requests.

Any tips on how to begin interacting with open source projects on the
copywriting and website development piece of things?

Thanks.

~~~
the8472
That depends largely on what you want to edit. Websites might be static pages,
generated from some simpler markup language or hosted on a form of CMS.
Documentation is often generated from source code comments to some extent.

If you can't easily figure out where it is stored and how it is generated you
should probably ask along with your inquiry whether the maintainers would be
interested in contributions in that area.

~~~
Mz
Okay, so, you are suggesting I figure out who the project lead is and email
them as my first step?

~~~
the8472
The preferred form of communication also depends on the project. Do they have
an issue tracker? If so you could probably file one along the lines of "Page X
could use some improvement" and ask whether they're interested and how it's
done.

Some projects use mailing lists, forums or even irc.

Open, group-based forms of communication are usually preferred because it
allows anyone qualified to respond instead of pinning it on a particular
person.

~~~
Mz
Thank you. This helps. I get told all the time "Just do X!" and then I try X
and it blows up in my face because it turns out you only do X under (long list
of conditions that no one ever told me and assumed I knew).

~~~
startling
I get anxious about this too sometimes, but in my experience the "long lists
of conditions that no one ever told me and assumed I knew" are hardly ever
relevant.

~~~
Mz
I don't get anxious. I get tired of doing what people told me would work and
having it go really badly.

~~~
knownothing
Complaining about freely volunteered advice people give you in a friendly and
helpful spirit is a good way to avoid getting it.

~~~
Mz
Well, that isn't what I was doing. Since you are not among those being
actually helpful to me in this discussion, you are more than welcome to stay
out of it if you feel that some remark of mine somehow constitutes bad
behavior. I have upvoted every single reply that was useful to me and said
_thanks_ twice.

~~~
knownothing
What were you doing? If someone volunteers advice, just be appreciative and
try it if you want. Don't slag them off if it doesn't work out for you. It's
not their fault they don't understand everything about what you need to do to
implement their advice.

------
cthulhuology
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.

~~~
kjksf
That doesn't sound like a sound advice.

If the author of the repo can't be bothered to look at the issue or a PR then
I don't see how they'll be receptive to emails.

Most projects don't have other ways of contacting the people involved (very
few list their e-mail addresses and even less have dedicated irc or slack
channels).

Yes, it happens way too often that issues and PRs are ignored but
realistically it's a strong signal to stop investing more time into such
projects because it's unlikely things will improve.

~~~
carussell
> If the author of the repo can't be bothered to look at the issue or a PR
> then I don't see how they'll be receptive to emails.

There's an assumption here that GitHub is automatically more convenient and
desirable than an email or other project management tools. That's not a
universal sentiment; not everyone wants to participate in the GitHub social
network, and even tools themselves that GitHub offers are a step down
depending on who you ask (like the pull request mechanism and issues and what
they try to pass off as a "wiki" and...)

So just because a project and its maintainers don't have a big showing on
GitHub, don't assume that means anything about the health of the project. It
may just mean they have better places and ways to spend their time and get
things done.

> Most projects don't have other ways of contacting the people involved

Why do you think the email field that shows up in git's log was put in place?
Honest question.

~~~
roblabla
Why do you assume everyone fills it up ? Honest question.

While it's true github isn't the "best tool" for everything in the world (what
is?), I find it mostly serves as a discovery tool. If I have a bug in a
project, I'll first look at the issues/PRs for other people who might have
fixed the damned thing. And it often turns out there are. The original author
might have abandonned the project, or he might have a different way to handle
contributions, but that doesn't matter to _ME_. I care about having my fix,
upstreamed or not.

------
atemerev
Step 1: stumble upon a terrible bug (or that really obvious missing feature
that _should_ be there) in your favorite library / framework / app.

Step 2: rant about it on HN / Github issues / whatever.

Step 3 (optional): try to reach developers on GitHub and get the obligatory
"pull requests are welcome" response.

Step 4: In frustration, clone the repository, fix the damn bug and submit your
pull request.

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.

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!

~~~
logn
> Step 4: In frustration...

Step 4 requires no frustration. It should be a relief you can fix it yourself
rather than hope for some opaque engineering team to maybe fix it at some
future date since your company doesn't have the Platinum Support package.

> Steps 5..41: ...

I think maintainers of small projects should do their best to merge whatever
is given to them without back and forth or delay--just a prompt and sincere
thanks. There's no reason to treat contributors like junior devs you're trying
to teach and guide. Sometimes that requires swallowing some pride in having
the code be just right or means you may want to fix up a few things after the
merge.

~~~
tananaev
As a maintainer of small project I would say that it depends. If the code is
really useful and contributor is not willing to fix any of my comments, I
would merge it anyway and fix it myself. If the code is so bad that it would
be easier for me to completely re-write it myself, I would reject it.

I'd like to think that my code review comments are reasonable most of the
time, so it doesn't usually take more than 2 or 3 iterations to complete a
pull request.

------
majelix
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.

For 1, it's mostly about knowing yourself. What projects interest you, and
where can you contribute?

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.

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.

~~~
boulos
So actually, I was thinking about #1 the other day as well. When you go to
GitHub.com, they now have /explore and /showcases. But, even if you find
something interesting (say [https://github.com/showcases/open-
journalism](https://github.com/showcases/open-journalism)), it isn't clear
that _any_ of those projects are suitable for contribution. Not everyone uses
a CONTRIBUTING.md, but even more so, I think many of the showcased projects on
GitHub fall into the "Free to make a copy of" not open to contribution.

So I keep coming back to what has been said elsewhere: the best way seems to
be to find a bug in something you use, realize it's open source and go from
there. That's unfortunately not a great way to mobilize the masses of people
that _could_ contribute, but don't have a particular project in mind (think
GSoC).

------
TAForObvReasons
> The way people (usually) contribute to an open source project on GitHub is
> using pull requests.

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.

------
chmike
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
[[https://github.com/blog/2042-git-2-5-including-multiple-
work...](https://github.com/blog/2042-git-2-5-including-multiple-worktrees-
and-triangular-workflows)]

------
Whackbat
For anyone that is new to contributing to projects using git for version
control I strongly recommend giving this tutorial a read:
[https://www.atlassian.com/git/tutorials/syncing](https://www.atlassian.com/git/tutorials/syncing)

Additionally, the best way to learn git is to use it so try all the examples.

------
fphilipe
I can highly recommend hub [1], which does steps 3, 4, and 5 in one command:

    
    
        hub fork username/repo
    

1: [https://github.com/github/hub](https://github.com/github/hub)

------
dibanez
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.

------
winterismute
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.

------
tbarbugli
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.

------
infodroid
There is a lot of overlap with Github's own guide to Contributing to Open
Source [1] and Forking Projects [2]:

[1] [https://guides.github.com/activities/contributing-to-open-
so...](https://guides.github.com/activities/contributing-to-open-source/) [2]
[https://guides.github.com/activities/forking/](https://guides.github.com/activities/forking/)

------
matiasz
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.

[1] [http://www.matiasz.com/2015/04/16/contribute-open-source-
rep...](http://www.matiasz.com/2015/04/16/contribute-open-source-repository-
github/)

------
exhilaration
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?

~~~
hzoo
Not the best way to find an open source project to contribute to but you can
check trending per language
[https://github.com/trending/csharp](https://github.com/trending/csharp) or
the top starred repos that are C#
[https://github.com/search?l=C%23&q=language%3AC%23&ref=advse...](https://github.com/search?l=C%23&q=language%3AC%23&ref=advsearch&type=Repositories&utf8=%E2%9C%93).

I'd be much easier to find a project you use or know about so you have a lot
more context into the project, it's usage, documentation, etc.

------
joelhooks
Here are some screencasts on this topic if that sort of thing interests you:
[https://egghead.io/courses/how-to-contribute-to-an-open-
sour...](https://egghead.io/courses/how-to-contribute-to-an-open-source-
project-on-github)

------
OhSoHumble
> 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.

Ah, my experience is that I'll submit a PR and it'll just be ignored until the
end of time.

------
smegel
7\. Work on your contribution

 _8\. Write tests!_

------
CharlesMerriam2
Wow! When you want to fix a typo, it can be as little as two hours!

~~~
cyphar
To be honest, typo fixes are fairly draining as a maintainer in large
projects. Especially if it's a small (one-line) fix.

Yeah, I get that you want to contribute and that's awesome (one of the best
things about free software is that everyone can contribute). But the relative
benefit of the actual change versus the time-to-check-the-PR and time-to-
reach-consensus-with-another-maintainer is quite low in most "typo fix" PRs.

If you're going to make a typo fix PR, please at least run a spell checker on
the file that you're doing the typo fix on (and even better run it on the
whole repo). Because at least then, your PR has a higher benefit ratio.

That being said, if you still make a typo fix PR I will merge it eventually.
Just be aware that I sigh out loud each time I get a notification for typo fix
PR, and I will almost certainly put other things higher on my priority list.

------
evantahler
Ya'll can contribute to www.actionherojs.com whenever you want!

------
ThomPete
But what about designers?

~~~
grzm
Projects need design as well. Websites, logos, manuals/documentation: there
are plenty of opportunities for designers as well.

~~~
Mz
[https://news.ycombinator.com/item?id=12881822](https://news.ycombinator.com/item?id=12881822)

If you could elaborate a bit on _how_ to get involved in the non-programming
piece for us non-programmers, like designers and copywriters, the world will
be a slightly better place.

Thanks.

~~~
grzm
I think the key is to find a project you care about, or care enough about that
you're willing to put in the effort to get to know the project and how it
works. Some communities will be easier to get involved with than others. It's
great that people want to get involved and volunteer their time and effort.
They also need to keep in mind that managing the community takes effort as
well, and that increases by some margin with every new contributor. Try to be
as self-supporting as possible.

That goes for any project you want to get involved with, regardless of how you
want to participate. And probably stuff you already know.

Want to work on the website? Documentation? Does the project already have
tickets or tags for these types of issues? Maybe a separate mailing list? Look
at the issue tracker. Subscribe to the mailing list. Look at the mailing list
archives. The commit history for the website or documentation. How recent is
the work? Who are the people involved? After you've gotten the lay of the
land, figure out where you might want to start and ask if people the project
would be open to having you work on it. Maybe take a stab at it yourself to
get accustomed to the project and tool chain. Take a look at what's there
already. How would you improve it? Compare it with sites or documentation for
other projects you think are good or enjoy using. What can you apply from
those sites to the project you want to work on?

For contributing and improving documentation, if you're new to the project,
you've got a great opportunity to help produce better content for new users.
What were your stumbling blocks? What was hard to find? What would you have
liked to see as you were getting started?

And remember, you're likely entering the epitome of bikesheds.[0] :) Wear a
thick skin! Some of my first contributions were in design and documentation.
People like well-designed things. And they can be a great introduction to a
community.

Was this helpful?

[0]:
[https://en.wikipedia.org/wiki/Law_of_triviality](https://en.wikipedia.org/wiki/Law_of_triviality)

~~~
Mz
I have a pretty thick skin. :-) As someone who is strongly people-oriented and
likes to debug the wetware/collective crap, I would say that the Law of
Triviality grows out of the need to hash out important human elements, such as
good communication protocols, trust between members, etc. It lays the
groundwork for doing good work when the chips are down.

Thank you for the long, detailed reply. I think this will help me.

------
dorianm
Or in a lot of cases you can use github's edit button ;)

~~~
besselheim
Agreed, it's much easier for quick bugfixes on code that you otherwise don't
want to invest your time into.

------
awkward_yeti
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.

~~~
cynicaldevil
Usually people begin by contributing to projects which they already use. For a
beginner, it might be better to start contributing to a project which is
mainly written in the language which they're familiar with. Also, try to find
a project which is beginner friendly; they usually have some issues marked as
'beginner' or 'good first bug', and also have a CONTRIBUTING.md page.

Bonus: A good idea is to start contributing to a project which contain
problems sets to be solved by coding the solutions in a particular language.
You could send PRs for creating/implementing some problems.
[http://exercism.io/](http://exercism.io/) is a good example.

------
i9182u79ikjnsk
_Shudder_. This embodies all that is wrong with open source development these
days.

Horrible GitHub workflow: corporate logos, octop^Hcat, CoC shoved in your face
on every commit.

I'm currently forced to contribute to a GitHub project, it is the most
annoying, bureaucratic and brainwashing workflow I've ever experienced.

~~~
delan
> corporate logos, octop^Hcat

Only two logos appear in the entire pull request process, and those are the
two small silhouettes that you see on every page.

> CoC shoved in your face on every commit

Codes of conduct? While they are becoming fairly prevalent, the GitHub
interface has no special understanding of them.

