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.
There is, however, value in submitting a PR without diving into the often stalemating "discussion" happening in a lot of projects. As much as I wish it weren't the case, I have found over the years that if your code follows conventions, works, and is useful, asking for forgiveness is much, much easier than asking for permission.
> Don't just create a fork, branch, and submit a PR without context. First, make sure the intent of your change is actually desired.
I think all that matters is that the change is something you want. If no one else has any need for it, you can continue using it as long as you wish to maintain your fork.
It's great to collaborate and share ideas before you start working, but if it's something you need, you'll do it even if everyone else says it's pointless.
| 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.
Understand code interactions: they scale N^2 with each new feature added. Specifically, each interaction your feature has with all the other features has to be coded, and then each new feature might interact with yours. This is the curse of scope freak.
It is the sole responsibility of the PM/owner of the project to select which features worth this.
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.
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.
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.
> 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.
The response was a long winded way of saying collaborate with people and don't work in a closed box. I was merely trying to summarize that open source can be a simple and beautiful thing. It's not complicated to get involved but tossing pull requests over the wall isn't the way to do it which brings us back to precisely what I said. Sorry you didn't find value in it.
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.
I agree, and it's one of the reasons why novice-to-intermediate programmers should try to pitch in to a project, even for something very minor. I remember making a pull request to a Ruby project and getting rejected and being told to fix all the rubocop errors, which made me aware of the existence of tools for auto-style-detection/linting, and of best practices in style that greatly improved my programming experience.
That kind of practical thing is not well-covered in tutorials and self-learning curriculums.
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?
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.
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.
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.
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).
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.
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.
Same here. Except I use 'myfork' as the name for my remote repo. Origin/upstream always got me confused when I first started learning Git, so I created my own naming conventions.
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.")
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.
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:
I'd say broadly that the right first step is to communicate with the maintainers somehow. Figuring out how is part of it. Check for activity - how many PRs, open and closed, does the project have? How often do they come in, and how quickly do they get commented on or merged by project maintainers? Are they linked to Issues on GitHub or some other system, and what's the activity level on those? Maybe they have a mailing list, Google Groups, IRC, Slack, or something else. Find it, see if it looks active, maybe send out a quick hello and see if anybody responds, and have a chat with them about what you'd like to do, if they're open to that, and how they would like for you to proceed. If they use GitHub issues or some other open issue tracker, you could open an issue for poor documentation or whatever, with an offer to fix it, and see if anybody responds.
Sounds complex, but you should only spend like 10-20 minutes on this. If you can't find clear signs of activity in that amount of time, there's a good chance that the project is abandoned or only accepts contributions from a private group. It may take a couple of days or so to get a response to messages on less active projects, that's okay. If you can't see any activity or get any response from maintainers in a reasonable timeframe, then don't bother. If your contributions are wanted and have a good chance of being accepted into the project, then somebody should be willing to write a few sentences to you specifically telling you so, and outlining how to contribute or where to find a current contribution guide.
And a lot of projects started adding links to edit the page you are currently on: http://babeljs.io/docs/learn-es2015/ (see the "edit this page" link on the header. For yarn it's on the bottom: https://yarnpkg.com/en/docs/. That at least makes it easy to edit a specific page for typos etc. Then you can just edit it from the website
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.
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.
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).
One thing I forgot to mention, this also depends on project size.
Larger projects, especially corporate- or foundation-backed ones, might have less-technical staff dedicated to the web presence/PR/outreach etc. which might use other communication channels than the developers.
> 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).
You don't necessarily have to know. Some exploration and just asking for pointers is often required.
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.
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.
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.
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.
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.
> 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.
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.
Check that there is not a mailing list first. This is where the "read the contributing guide" kicks in.
I for example have quite a lot of filters, that make sure I reply to mailing lists, but if you email me directly, you may end up lumped in with all the commercial "include my $thing in your project please" emails (purely by accident)
While it's true you might want to email the author and all, having a PR is great for one thing: letting other people looking for the bug/feature find the fix before it's upstreamed.
This is what I usually do with my PRs. I first submit the PR so it's there for other people to grab if they need it, and then I'll look into the "proper" way of upstreaming the fix.
This avoids duplication of work and enhances discoverability.
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!
Disclaimer: I am an akka and akka-http community contributor. I don't know how this works for other projects.
But I don't think the process is as painful as you describe in the akka world. My experiences are quite to the contrary. The community here is warm and welcoming. But, please look at this from the other side. Would you use the software in your mission critical application if the project was accepting quickly contributions from random strangers on the internets?
I am half-joking, of course; when I have submitted my first (minor) PR to Akka, I thought "wow, that is probably the most complicated code I ever had to follow through!" So I expected that I could get many things wrong, and will have to correct them first. So I did.
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.
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.
I remember when my first ever request was accepted. The fev thanked and with next release I saw he changed few things in my code, small things. Nevertheless it made me more comfortable submitting pull requests and really happy at the time.
> 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.
As a maintainer, I can completely see where you're coming from here and some of nits that I have against PRs probably seem quite trivial. However, if you have a fairly large project then as a maintainer the onus is on us to make sure that things don't break (and that the project remains manageable). Not to mention that the argument people use (that we should just make a follow-up commit that fixes the PR so it's actually acceptable) doesn't _really_ work if you're someone who has to do bisects often -- I'm not going to merge code that is clearly wrong in several places (unless the code is returning a "not implemented" error).
It's not a pride thing, as maintainers we have much less time than the contributors (there are fewer of us than there are of you) so we can't carry every PR that someone drops on our issue tracker.
Of course, for runC we have automated testing that verifies that things like golint and gofmt succeed (so we don't have to waste time going back-and-forth with contributors about it). Lots of smaller projects don't do this, which leads to nothing but annoyances for contributors.
Also, in general when reviewing a change I try to state whether or not the idea is sound. If I am commenting on your choice of variables or how you've structured your algorithm, that means that I like the idea (and is an implicit "I will merge this once you fix <these set of nits>"). Not all maintainers do this, but most learn to do this quite quickly.
> 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!
And get the same pay as everyone else that doesn't play any of these reindeer games, because recruiters already know how to find us and setup the interviews!
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.
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), 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).
> 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.
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.
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.
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?
> 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.
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.
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.
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.
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.
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.
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/ is a good example.
For almost any project there is an infinite amount of work to do. Check out OpenHatch for opportunities, or just dive in for things you rely on. Big communities are great too, checkout Linux or one of the distros:
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.