Every so often I come across a repo on github that really interests me and that I would really like to work on, but it is very difficult to get into the guts of actually helping out. How do you quickly get into it enough to help out?
Most projects are lacking good documentation and in the process of writing documentation, you have to learn how it all works.
I absolutely second this. Having nonexistent, outdated, or incorrect docs can make the new user experience pretty bad. Fixing even small errors helps many other people adopt the software you’re updating docs for.
Write a test, or document some code. Emailing the owner and asking how you can help out is also useful.
I’ve also read some code and then refactored it after, if I find it confusing to reason about.
I like this idea, do you normally submit your refactors as pull requests afterwards? or is that just for personal practice? If you submit PRs, do maintainers normally accept refactors?
Full disclosure: I’m now an employee at twitter, although I contributed to twitter OSS before I was employed by them.
Different maintainers feel differently about it. I got excited about twitter/algebird a couple years ago, and submitted a couple of only refactoring pull requests. It’s very inexpensive for them to accept the refactor, since they only have to read the code and click the merge button. It might be more complicated for other repos–for example, I’m a maintainer on twitter/finagle and we need to go through a thorough review process internally, and also make sure that it passes all of our internal CI tests. However, we still commit documentation changes, including typo fixes.
It really depends upon the kind of maintainer. Some maintainers never look at pull requests. Other maintainers try to constantly be gardening their pull requests. Generally, only really big projects will reject tiny commits.
Definitely depends on the project and maintainers. As another example, there are some projects that would prefer you to open a ticket first talking about your suggested changes.
E.g. Someone opens up a PR with 1000 lines of changes (all good changes!)…but its on code that is slated to be depreciated, removed, or the feature changed completely. Now the maintainers are in a rough spot.
Those are kinda extremes, but it makes the point. Unless the PR is small, I like to open a ticket first and get feedback first. Works better for everyone imo.
My advice? Just Use It™. The lion’s share of my open source contributions have been not to projects that I explicitly set out to contribute to, but projects that I was just using for work or fun and found some sort of bug or shortcoming in that I decided to fix.
This is more-or-less how I started contributing to Chisel. Using a new language/library/DSL in larger projects tends to expose a lot of bugs that the test suites don’t detect.
Find an itch to scratch, and scratch it.
I started by looking at Github projects, and seeing how they work.
Not only the code, but also how the issues and pull requests work.
Then find an issue that people are having, and have a crack at fixing it. Even if it’s a small documentation change, or a typo in the code, every contribution helps, especially while seeing how it all works.
That’s my two cents anyway :)
Here’s an article written by a friend of mine about this very topic:
Each project works differently, but I agree that most project maintainers love to see some documentation. It’s usually lacking and it can really help you familiarize yourself with how the code works. I see others have mentioned refactoring hairier code; this is a great idea, but I would be careful about this as a newcomer, since some maintainers take a lot of pride in their work and may react poorly to a newbie coming in and calling shots.
Another thing I’ve learned is that one of your most valuable tools will be your e-mail client. Communication with the maintainers and existing community is key! Unless it’s been established that certain work needs doing (a feature request that the maintainer approves of but has no time for, or a bug fix), you should check with the community to see if the change you want to make is something that conforms with the spirit of the project. Otherwise you may end up spending time and effort working on something that the maintainers won’t merge in, even if they recognize your good intentions.
Finally, it’s a lot easier to start with a project if you have something to work on. You know what they say: necessity is the mother of invention. It’s a lot easier to get started if you have a bug to fix or a feature you’d like to add.
For me it’s usually fixing typos in documentation or in the code itself. If the documentation doesn’t make sense or if it’s confusing, I’ll send in some changes to make it clearer.
Opening a pull request allows a conversation to start. The owner may not realise something is confusing because they’ve been elbows deep from the start, a new set of eyes can throw up new problems to fix.
The main thing is using the project to find out what’s not working properly.
I can help you get started if you’re interested in learning Haskell. Familiarity with a community and the individuals in them can help you to know where your efforts should or shouldn’t go.
I have found it really helpful to join the IRC channels of open source projects I’m interested in and just start trying to answer questions. You’ll get a good feel for what things need to be improved and will probably meet other contributors in the process.
There are open-source projects that have bounties. These projects are more likely to accept contributions, and you are also likely to get a monetary reward for your work.
A site that I know and lists such bounties is Freedom Sponsors
One thing I like to do is to smooth out the onboarding process. Nevermind new features or bugfixes you want to contribute, how long does it take you to actually get the system downloaded and running with the test suite wired up? If its more than a few minutes then you can have dramatic compounding effects just by building/documenting a quick-start process for future contributions.
Inertia is the killer when it comes to drive-by OSS contributions.