r/programming • u/vivaladav • Nov 05 '16
How to contribute to an open source project on GitHub - a step-by-step guide
http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/361
u/Bl00dsoul Nov 05 '16
What i'm missing is how to actually find your way in a massive code base with barely any documentation, and figure out where to make your changes without spending weeks reading the full code base...
94
u/tsnErd3141 Nov 05 '16
I guess everyone faces this problem. I want to contribute but I don't know where to start and the thought of reading the entire code base scares me.
51
u/kryptomicron Nov 05 '16
Don't let being scared stop you.
First, what's the worst that happens? You give up?
Second, every (?) language has something like 'print ...' that can log its output to a console or file. Add those statements/calls/etc. liberally to the code.
Third, the code (any code) probably is as badly written or badly documented as you think it is. Rewrite as you read it, just for your own edification.
23
u/tsnErd3141 Nov 06 '16
First, what's the worst that happens? You give up?
I try a bit, then at the first complex bit of code I think the author is a genius, get an inferiority complex and then give up.
-3
u/giantsparklerobot Nov 05 '16
Please don't add a bunch of print statements to code.
The branch where you put the print statement may never be hit, leading to adding yet more print statements to figure out why that is
When you go to submit a PR the person doing the merge now has to spend time denying lines where you left in your print statements 2a. You may forget where you stuffed all those print statements and make it harder to navigate the code
Code with existing console output can hide your prints just due to volume and lead you down the wrong path figuring out why your print statement "didn't" execute
Walking through code is a great exercise to learn to use a debugger.
Learn to use a debugger, it's superior in pretty much every way to debugging with print statements
Print statements may have non-obvious performance/functionality affecting side effects
4
u/MisfitMagic Nov 05 '16
The best place to start is always the list of issues. This would give you an idea of something that actually_needs_ fixing.
Another thing that's helpful is extending functionality somewhere you already know there's a feature gap.
A logging application, for example, could be extended to include logging to third party apis, like slack or AWS.
-1
u/gnx76 Nov 05 '16
The best place to start is always the list of issues. This would give you an idea of something that actuallyneeds fixing.
Great. The opened issues are those that the people who have known the software for years don't know how to solve, or deem too difficult to work on for the benefit it would bring. Sending a newcomer on this is perfect to put him off.
6
u/captainAwesomePants Nov 05 '16
One of the focuses of good software engineering is maintainable, navigable code for just this reason. If you need to carefully read the whole program to figure out how to make a change, that's no good at all.
7
u/FallingIdiot Nov 05 '16
Yup, this. The most important thing you need to do is to learn how they've architected the thing. Once you get a feel for that, it becomes easier and easier to find your way.
3
u/lmcinnes Nov 06 '16
If it's a good project then despite being large it is also modular. That means that you shouldn't have to read and understand everything, but can just focus on some small module that is (relatively) self contained. This is how any of the contributions I've ever made have worked -- sure I don't know how everything works, but I can understand this little corner over here, and soon enough I can submit an improvement, or fix and issue with it.
21
u/nicholas-leonard Nov 05 '16
Open an issue and ask. Or look at the main contributors and ask them by email (it is often listed on github profiles).
-9
Nov 05 '16
So it gets buried together with the other tons of issues in that uncoordinated mess that is github issue tracker.
12
Nov 05 '16
So what if it does? At least you have a chance of getting a response versus not posting anything at all.
10
Nov 05 '16
What always helps me (professionally and in open source) is just search the pull requests and git log. Usually you're enhancing or fixing an existing feature, so just search for that feature until you find the commit or group of commits that added it. If you find a decent PR, you have a whole discussion around the changes and all the relevant right in front of you.
15
Nov 05 '16
How do you do this when you start a new job? You start at main, look at the tests, ask questions on email lists and chat rooms.
Also many open source projects are not giant behemoths. Not everything is the Linux kernel.
Many are libraries you use and maybe want a new feature. Chances are you've already dig through the source to know if it's even possible because you tried to extend it. at that point you know more than you think you do
0
Nov 05 '16
7
Nov 05 '16
if the tests written in industry are anything like the ones I've encountered out in the wild, that's where the most unspeakable horrors are committed
4
Nov 06 '16
That's the kind of thing that only gets easier with experience. It's a good idea to contribute to some smaller projects when you're starting out, and then work your way up. Smaller code bases tend to be much easier to understand, and the maintainers are often friendlier and more helpful because they're delighted to have anybody at all helping them improve their project.
2
u/eriman Nov 06 '16
Smaller code bases tend to be much easier to understand, and the maintainers are often friendlier and more helpful because they're delighted to have anybody at all helping them improve their project.
Yes oh my god
3
u/kryptomicron Nov 05 '16
You're not necessarily missing anything. Sometimes there's no other way to find your way in a code base other than reading a lot, or even all, of it. That's usually a pretty big 'smell' that the code isn't very well organized tho and could reasonably dissuade you from contributing.
8
u/Manishearth Nov 05 '16
jdm gave a talk on this once
4
u/lfairy Nov 06 '16
And on the other side, Manishearth wrote an article on attracting new contributors.
8
3
u/vine-el Nov 05 '16
Contribute to smaller or better documented projects? If they aren't making it easy to contribute, don't bother.
0
Nov 05 '16
17
u/thomas_stringer Nov 06 '16
Oftentimes a lot of larger repos even require an accompanying issue for things like milestone tracking.
Tying an issue to a PR is usually a really good rule of thumb. Of course there are always exceptions.
3
u/Thought_Ninja Nov 06 '16
Honestly, my MO in learning how a large project is built is to make a fork, make a "time-to-break-shit" branch, and do exactly that, then rinse and repeat.
1
-1
u/thockin Nov 05 '16
Start at main() and walk through it. If you can go 30 minutes without wanting to comment, rename, or refactor something it must be a great codebase. Make small changes. Hack a little.
The only way to learn a codebase is to hack on it. Even if you toss out your changes at the end.
49
Nov 05 '16
Start at main() and walk through it
Good luck with that with any framework-based code.
→ More replies (9)0
u/NoMoreNicksLeft Nov 06 '16
I just put up my own project recently. It's pretty bare-bones, but I'm trying to make it modular so that if someone wanted to add features, it should mean maybe adding a few lines to a config file or two, and the package for the new logic.
Still, knowing that from looking at the code (my code's pretty bad, though I'm trying to keep this project clean) is probably impossible.
You've made me think that when I get around to writing documentation, maybe I should write contributor-specific docs too, and post them. Thank you.
0
-1
u/slobarnuts Nov 05 '16
That's easy. Just find an open source project and try to use it. When you can't do what you want or find a bug, fix it and git.
68
u/asmx85 Nov 05 '16 edited Nov 05 '16
Cool short write up. The one thing that i would add is rebase. You probably need more than one commit to fix the issue or complete the task you wanted. And its often that you missed something (comments, documentation, right formatting, simple mistakes (double semicolon ;;), missing test case etc.etc. ) And you don't want all that correction steps in your upstream repository but only the clean one commit.
I can only advise for everybody to rebase and squash your commits, upstream guys and gals will love you for it :) ❤
28
u/echo-ghost Nov 05 '16
you can rebase pull requests in the pull request UI now, when you merge it will rebase/merge/squash-into-one-commit depending on what you want
12
u/asmx85 Nov 05 '16
Thx for the hint. Personally i try to stay away from UI and GUI for the most part. Maybe its something from the past but the only times we got "problems with git" in our team it was mostly due to some IDE Git Gui Shenanigans and i couldn't even help so i encourage everybody i work with to use the shell, there is not much one has to learn to use git. You can have some cool diff / history GUI tool but i don't use it much either.
12
u/virgoerns Nov 05 '16
Rebase only local commits however. If you already pushed them to your fork, leave them. Squashing everything is overrated since you can always do
git log --first-parentto get nice linear history and otherwise you lose the history of your struggles which might actually be useful to someone. Better focus on good description for your merge commits.2
u/ReversedGif Nov 06 '16
If you have a feature fork that you're working in, it's likely that only you have it locally anyway, so squashing isn't a problem (and very common in this situation).
6
4
u/SnowdensOfYesteryear Nov 05 '16
Or have a good enough discipline not the make garbage commits that pollute git log. Each commit should be good enough to be it's own PR.
Please don't squash everything into one commit. Especially if you have one ginormous feature.
Edit: of course anything goes in your local branch.
2
41
Nov 05 '16 edited Nov 05 '16
Step 1: try to understand what the hell is going on.
Step 2: spend 3 days trying to make that change you really want
Step 3: open the PR.
Step 4: get it rejected two months later because it's not appropriate, not in line with coding style, don't like it.
Step 5: repeat. or not. Get out and go have a life. Unless it's your job, in that case, sucks to be you
0
u/elmundio87 Nov 06 '16
Hell if the original repo's maintainer doesn't like your changes, just maintain your own fork and occasionally merge in the upstream commits.
9
28
u/Purkinje90 Nov 05 '16
They missed a great opportunity to title this Go Fork Yourself
8
u/webby_mc_webberson Nov 06 '16
And then some bitch gets you fired because it'snot rrespectfulof women in the iindustr. No thanks.
0
Nov 06 '16
6
Nov 06 '16 edited Mar 07 '24
I̴̢̺͖̱̔͋̑̋̿̈́͌͜g̶͙̻̯̊͛̍̎̐͊̌͐̌̐̌̅͊̚͜͝ṉ̵̡̻̺͕̭͙̥̝̪̠̖̊͊͋̓̀͜o̴̲̘̻̯̹̳̬̻̫͑̋̽̐͛̊͠r̸̮̩̗̯͕͔̘̰̲͓̪̝̼̿͒̎̇̌̓̕e̷͚̯̞̝̥̥͉̼̞̖͚͔͗͌̌̚͘͝͠ ̷̢͉̣̜͕͉̜̀́͘y̵̛͙̯̲̮̯̾̒̃͐̾͊͆ȯ̶̡̧̮͙̘͖̰̗̯̪̮̍́̈́̂ͅų̴͎͎̝̮̦̒̚͜ŗ̶̡̻͖̘̣͉͚̍͒̽̒͌͒̕͠ ̵̢͚͔͈͉̗̼̟̀̇̋͗̆̃̄͌͑̈́́p̴̛̩͊͑́̈́̓̇̀̉͋́͊͘ṙ̷̬͖͉̺̬̯͉̼̾̓̋̒͑͘͠͠e̸̡̙̞̘̝͎̘̦͙͇̯̦̤̰̍̽́̌̾͆̕͝͝͝v̵͉̼̺͉̳̗͓͍͔̼̼̲̅̆͐̈ͅi̶̭̯̖̦̫͍̦̯̬̭͕͈͋̾̕ͅơ̸̠̱͖͙͙͓̰̒̊̌̃̔̊͋͐ủ̶̢͕̩͉͎̞̔́́́̃́̌͗̎ś̸̡̯̭̺̭͖̫̫̱̫͉̣́̆ͅ ̷̨̲̦̝̥̱̞̯͓̲̳̤͎̈́̏͗̅̀̊͜͠i̴̧͙̫͔͖͍̋͊̓̓̂̓͘̚͝n̷̫̯͚̝̲͚̤̱̒̽͗̇̉̑̑͂̔̕͠͠s̷̛͙̝̙̫̯̟͐́́̒̃̅̇́̍͊̈̀͗͜ṭ̶̛̣̪̫́̅͑̊̐̚ŗ̷̻̼͔̖̥̮̫̬͖̻̿͘u̷͓̙͈͖̩͕̳̰̭͑͌͐̓̈́̒̚̚͠͠͠c̸̛̛͇̼̺̤̖̎̇̿̐̉̏͆̈́t̷̢̺̠͈̪̠͈͔̺͚̣̳̺̯̄́̀̐̂̀̊̽͑ͅí̵̢̖̣̯̤͚͈̀͑́͌̔̅̓̿̂̚͠͠o̷̬͊́̓͋͑̔̎̈́̅̓͝n̸̨̧̞̾͂̍̀̿̌̒̍̃̚͝s̸̨̢̗͇̮̖͑͋͒̌͗͋̃̍̀̅̾̕͠͝ ̷͓̟̾͗̓̃̍͌̓̈́̿̚̚à̴̧̭͕͔̩̬͖̠͍̦͐̋̅̚̚͜͠ͅn̵͙͎̎̄͊̌d̴̡̯̞̯͇̪͊́͋̈̍̈́̓͒͘ ̴͕̾͑̔̃̓ŗ̴̡̥̤̺̮͔̞̖̗̪͍͙̉͆́͛͜ḙ̵̙̬̾̒͜g̸͕̠͔̋̏͘ͅu̵̢̪̳̞͍͍͉̜̹̜̖͎͛̃̒̇͛͂͑͋͗͝ͅr̴̥̪̝̹̰̉̔̏̋͌͐̕͝͝͝ǧ̴̢̳̥̥͚̪̮̼̪̼͈̺͓͍̣̓͋̄́i̴̘͙̰̺̙͗̉̀͝t̷͉̪̬͙̝͖̄̐̏́̎͊͋̄̎̊͋̈́̚͘͝a̵̫̲̥͙͗̓̈́͌̏̈̾̂͌̚̕͜ṫ̸̨̟̳̬̜̖̝͍̙͙͕̞͉̈͗͐̌͑̓͜e̸̬̳͌̋̀́͂͒͆̑̓͠ ̶̢͖̬͐͑̒̚̕c̶̯̹̱̟̗̽̾̒̈ǫ̷̧̛̳̠̪͇̞̦̱̫̮͈̽̔̎͌̀̋̾̒̈́͂p̷̠͈̰͕̙̣͖̊̇̽͘͠ͅy̴̡̞͔̫̻̜̠̹̘͉̎́͑̉͝r̶̢̡̮͉͙̪͈̠͇̬̉ͅȋ̶̝̇̊̄́̋̈̒͗͋́̇͐͘g̷̥̻̃̑͊̚͝h̶̪̘̦̯͈͂̀̋͋t̸̤̀e̶͓͕͇̠̫̠̠̖̩̣͎̐̃͆̈́̀͒͘̚͝d̴̨̗̝̱̞̘̥̀̽̉͌̌́̈̿͋̎̒͝ ̵͚̮̭͇͚͎̖̦͇̎́͆̀̄̓́͝ţ̸͉͚̠̻̣̗̘̘̰̇̀̄͊̈́̇̈́͜͝ȩ̵͓͔̺̙̟͖̌͒̽̀̀̉͘x̷̧̧̛̯̪̻̳̩͉̽̈́͜ṭ̷̢̨͇͙͕͇͈̅͌̋.̸̩̹̫̩͔̠̪͈̪̯̪̄̀͌̇̎͐̃
8
u/beefsack Nov 06 '16
The most, most, most important thing to do before contributing to a project is to open discussion with the maintainers to make sure:
-
It's something they want.
-
You're heading in the right direction with it.
-
Whether they already had plans for it, and is potentially blocked by other work.
2
5
u/cyentist Nov 05 '16
One small thing I want to add is that if you have a minor contribution (maybe fix typo in docs or something) it is very easy to edit the source code directly in github without having to fork/pull/edit/push/pull-request.
10
Nov 05 '16
First and last time I tried it to change string literal, it inserted
\0for some reason, which I didn't notice. It was **FUN** to debug.2
4
Nov 05 '16
It's a bit sad that contribution to open-source seemingly boils down to GitHub pull requests when there are so many other ways. Back in the days when I used KDE on FreeBSD, I was as a contributor just because I reported errors in the documentation as I was learning to develop KDE applications.
2
u/cristinereyess Nov 07 '16
Yes, I know about this, GitHub is the best Platform to contribute an open source project
0
Nov 05 '16
66
Nov 05 '16
Receiving several comments about how your coding style doesn't match the coding style guidelines
I mean, this is straightforward? Fix your style.
5
u/beefsack Nov 05 '16
I have to be honest, OP doesn't sound like a very valuable contributor.
If you want to contribute to a project, you have to understand they have their own goals and way of doing things. Some rules and guidelines need to be enforced, otherwise the ensuing anarchy turns the project into chaotic mess.
-3
u/WhatTheGentlyCaress Nov 05 '16
or, leave it for someone else to fix.
If I make a change, it gets delivered direct from 'my' working code. If they don't like the format, someone else is welcome to change it to 'house' style. It is working on my side, which was the itch I needed to scratch.
16
Nov 05 '16
In that case, you're not really trying to contribute to open source, just quiet your OCD as it were.
It takes you virtually no effort to conform to the hosting project's code style. You already have the code locally. Don't make someone else switch contexts etc just to fix your laziness.
0
Nov 05 '16
23
Nov 05 '16
I have one rule: any style that passes linting and validation (e.g. pep8) is valid style. If you have any bizarre requirement about the coding style, it is bollocks until you write a module for the linter that checks for that.
3
u/LKS Nov 05 '16
If they are so anal about the style, they will probably have some Lint settings so your IDE shows you where your code doesn't comply.
1
u/vinnl Nov 06 '16
For the maintainer I think it'd save time for both of you if they'd just implemented the code style changes themselves and then refer to that in a comment for a next time you submit a PR - which has just been made more likely.
42
u/civildisobedient Nov 05 '16
Not receiving any response for your pull request for months, if ever at all
This is the one that infuriates me off the most. You can have a hundred users all clamoring over a bug. Someone does the work, writes the unit tests, submits the pull request... all you have to do is fucking CLICK A BUTTON to merge it in. But... nothing.
Here's an example from Liquibase. Liquibase's big claim to fame is that it's supposed to make schema changes agnostic to the database layer. But here's the breaking difference that forces you to write separate code for H2 databases. There's been a fix out there for a fucking year and a half. Just SITTING out there. Multiple response from people asking, "What in the ever-loving fuck is the problem, here, and when will this get merged?" have fallen on deaf ears.
Developers are offering their time freely to help integrate the code. Yet the maintainers do nothing. Then, months later, after the codebase has migrated and changed, all they say is "make another pull request with the latest code." So they do. And the response? NOTHING.
It's maddening.
18
4
Nov 06 '16
all you have to do is fucking CLICK A BUTTON to merge it in.
And take responsibility toward the users for defending it. Maintaining it. Ensuring that the direction the project goes into is a good one, so that in a few years you'll still want to use it yourself, at least.
Not to mention that nearly everybody accidentally does 90% of the work - and if you merge in a few of those "free" changes you'll have a full extra ticket just to get things back to clean again. Add to that that usually a few pull requests collide so you get to pick who to piss off - but not nobody.
2
u/civildisobedient Nov 06 '16
Which is why there are tests: to free you from the fear of breaking changes.
Or, alternatively, you can be so scared of progress and outside help that your project stagnates and you completely miss the benefits of open source.
13
u/lol-jk Nov 05 '16
It's a great for maintainers to automate as much as possible so that they can just review it.
Receiving several comments about how your coding style doesn't match the coding style guidelines
At least for javascript projects we run a linter like ESLint so that fails on CI so no one has to write anything to get you to fix it and there's usually a simple autofix for it. This is what we do have in babel: https://github.com/babel/babel/blob/master/Makefile#L20-L27
Yeah its difficult on both sides? Maintainers have to deal with the hundreds of issues and PRs to look over and it might be harder to look at PR that touches part of the code you don't know much about yourself, the use case, etc - need a lot of empathy that you probably don't start out with. Usually there's a chat somewhere: irc, gitter, etc (we have a slack) so you can ask questions.
Hopefully you can find a project that you use regularly and are able to get more involved in - not exactly how I got involved but with time it can happen (even if you don't know anything).
5
u/ashdnazg Nov 05 '16
In some projects there's an irc channel or something similar where the maintainers hang out and you can use it to communicate with them while/before writing your patch.
Unsurprisingly, this will increase the chance of merging considerably.
4
u/vnen Nov 05 '16
As someone who can actually merge PRs in an active OSS project, I can say that this is pretty much true, unfortunately.
One of the major problems is that if you make a PR in a complex part of the code (like optimization) the chances of getting merged drops a lot. Few people can review such changes and it dims the willingness of the author to make further improvements.
I'm not knowledgeable enough to merge such things and making the main dev to review it soon is quite a battle sometimes.
2
Nov 05 '16
There may also be contributor agreements, since usually it is best for a project to have as few copyright owners as possible. Otherwise it can become a giant legal mess hunting down people who wrote a patch a decade ago.
2
Nov 06 '16
Not receiving any response for your pull request for months, if ever at all
The story of why there are 50 projects to solve one problem. Because while software engineers love to work for free, project managers do not, and software engineers don't give a shit about your desire to improve their project that works just fine for their use case.
3
u/BilgeXA Nov 05 '16
Project maintainer examining your pull request and deciding it's not going to be merged
It's not really an issue if your PR is rejected. Maintain a fork, and if you're correct that your code is more valuable, people will migrate to your fork instead.
12
u/vnen Nov 05 '16
Easier said then done. If this is successful you become a project maintainer, which is not something everyone wants (or has free time) to do.
4
3
u/aarace Nov 06 '16
in my experience, probably half of my PR were declined, only to have the original author implement it themselves.
a real "fuck you, but thanks for the idea".
5
u/ReversedGif Nov 06 '16
Maybe the author can implement it better, given his better knowledge of the code, or already had a solution in mind, but just needed someone else solving the problem to generate the impetus for the author to finally implement his own solution?
I've been on both sides of this in the past. However, I've tried to give the pull requester credit by merging the pull request, then making my changes/rewrite on top of it.
1
u/rrkpp Nov 06 '16
The one time I tried contributing to an open source repo, the maintainer misread the code in my PR, closed it for being broken, then realized his mistake and just implemented the exact same code himself lol
1
u/Lindby Nov 05 '16
Clone it, and start poking around. Search for different keywords related to the thing you want to fix. Once you find anything you think might be relevant, try to figure out how it is intended to function.
1
1
-2
-1
-7
-14
u/aurisor Nov 05 '16
Generally speaking, if you need a guide to open a pull request, the odds of you being able to contribute to a codebase are pretty low.
2
1
u/trrSA Apr 03 '17
I don't know, but after reading the article and the comments here, I suddenly have the confidence to contribute to some of the projects I use and want to see some fixes and changes to. I know I can code well, but just never felt the push to contribute.
-43
u/jose_von_dreiter Nov 05 '16
Pull request? A pull is when you download code from the repo. A push in when you upload.
33
14
u/aristotle2600 Nov 05 '16
Right, but as a Some Guy On The Internet, you don't have write permission to anything. Instead, you have to make your changes to your copy, then say to the project maintainer "Hey, I think my copy of your code is now slightly better than yours because of some code change I made. Why don't you pull my code into yours?" You're not pushing your code to then because you're not allowed; you're asking them to pull your code in to theirs. Hence, pull request.
1
Nov 06 '16
I understand why you're getting downvoted, but I do realise that that is a fucking confusing term.
742
u/[deleted] Nov 05 '16
Find popular repository by well known organisation/individuals
Fork repository
Fix typo in documentation
Create PR
PR accepted (no actual code changed)
Put on CV that you contributed to large OSS project and are an expert in Git
Steps 1-4 are done entirely on github.com.