How To Contribute To Open Source Projects Effectively

Here are some pointers accumulated from having contributed – often successfully, but occasionally less so – to several open source software projects over the past few years.

I've programmed for several (actually, many…!) years, now, but I've only started working on open-source software software relatively recently.

Here are a few pointers gathered from those recent experiences.

This article focuses on the GitHub Issue/Fork/Pull Request workflow, but most of what I say should be applicable elsewhere.

If you're new to the goodies of open source then it might seem like it, but it's NOT your project!

Just because you're allowed to offer changes to a project, and to take your own copy to do whatever the license allows (which might be, but isn’t always, whatever you want), that doesn't mean it's your project. Not everyone is equal in open source and you're definitely not equal, when you're brand new to a project!

All open source projects have an existing community, especially the project maintainers who are in it for the long run, and likely to still be working on it and maintaining the code (including any code you added, and they decided to adopt) long after you have moved on.

Don't underestimate the time it takes to make a seemingly simple change – really cleanly, and with all required tests – so that the results are suitable not just for you, but for the hopefully many other users of the project.

Don't underestimate the work required to review a pull request, either.

What should a Pull Request look like?

A open source Pull Request should add - or change - just one feature of the software, and it should be the minimal set of changes needed to make that change cleanly; for instance, additional code tidying, done to make your life easier, does not make life easier for the project maintainer when reviewing your changes.

Too small a change - particularly just code tidying - is not worth submitting; it's more trouble to review that it is worth, even if the change in some sense does 'need' making. A small but genuine typo fix, especially in documentation, probably is worth offering back, however.

Too big a change (i.e. too much in one pull request) is also useless: it's so much work to review that it's almost certainly more work a) to understand it, and b) to fix (or suggest fixes to) any issues, than it would be for the maintainer to do the work from scratch themselves. It also shows that you haven't been prepared to do the work needed yourself to split up your pull request into single features, something which would have very considerably helped the maintainer in reviewing your work.

If you're still considering making large changes, tread very carefully. Once again, the public master branch is not your project just because it's open source! It's crucial to get an active, two-way discussion of the issue going, if you want to have a chance of moving forward with what you're planning. The best place to do this is almost certainly on the Issues page for the project.

Open an Issue

Always create an Issue describing the problem, even if you have a Pull Request ready that you believe fixes it, and even if that seems like direct duplication to you. It's simply how projects on GitHub - and most similar sites - are structured.

Feature requests and support requests don't belong on the Issues page

The Issues page is for suggesting genuine Issues, and it's not (normally) the right place for making feature requests; unless you know the code well enough that you are prepared to offer to implement the feature yourself. If you want to make a feature request, but don't know how (or don't have the time) to implement the change yourself, there is usually a different forum for this: check out the GitHub project README file, and any other project homepages and documentation, to find out what channels are available.

The Issues pages are definitely not there for support questions (except where the issue is a genuine bug; in which case the usual rules about writing a good bug report apply). Instead, try Stack Overflow or a similar appropriate site.

Wait for a response

Sometimes, you'll try to raise an Issue, but you won't get a timely response... where by 'timely', I mean that you should allow at least several days! Open source maintainers are often one person bands, and are usually really busy with their day job, as well as with the open source software that they are maintaining - often in their personal spare time.

If you don't get a response, it's not always strictly necessary to gain prior approval before doing a small unit of work which you believe has an obvious benefit.

Don't be surprised if you're completely ignored, however. (Again, open source maintainers are often one person bands, and typically also really busy with their day jobs!)

An initially ignored Pull Request doesn't necessarily mean that the Pull Request was no good.

You may still find that the Pull Request eventually gets picked up by the maintainer(s), possibly with requests for changes.

Be very prepared to make the changes which the maintainer asks for!

Even if the busy(!) maintainers ignore you, you may find that other users of the project like your suggestion and add their support (in terms of emoji reactions or comments). In that case a polite but not over-persistent follow-up is appropriate. Even then, you may still be ignored; remember, maintainers are often one person bands, and busy!

And even then, your Pull Request may not match where the maintainer wants the project to go, or may not match the current thrust of their work on the project - which is already using up their own limited time! There really isn't much you can do in that case except leave it.

(Almost certainly) don't maintain a long-term fork the project, not even a private one for your own use

A fork is your own copy of the project, which you take and work on. The basic act of forking (i.e. essentially just taking your own copy, though GitHub has specific workflows to support this), then making and debugging changes, then offering them back to the main project is all just how open source works. That's absolutely fine.

But you'll often read and hear people talk about 'forking' an open source project in a much more loaded sense. What they mean is: splitting and maintaining your own version (aka fork) of the project, for the long term.

There are two variants of this, each with considerable disadvantages. The first one is more likely what you're considering(!), but even so... watch out!

The problem with private forks

If you can't get a change you need accepted into an open source project it can be very tempting to maintain your own, modified version of the software, incorporating the changes you need.

The trouble with this is future maintainability:

• Q: What happens when the original project is updated to keep up with the inevitable changes in the surrounding software landscape?
• A: You're going to have to keep re-doing your changes onto the upstream project, and this is going to get less and less trivial, the more the upstream project changes.
• Q: What happens when someone else (in your team; or employed in the future to work on the software you've developed) has to maintain and update your software?
• A: Basically, you've left your company or client reliant on an un-maintained library. Bad!

What could you do instead? A no-doubt incomplete list includes:

• Live without the change
• Find a different work-around
• Find a different project that does what you need

The problem with public forks

The various Linux desktops all arose as forks of each other. So have the various Linux distributions themselves. So major, public forks of well-known projects can work.

But they usually don't!

• Why should someone else use your project (starting with a grand total of 1 users), over the original?
• Can they know that you are going to support and maintain the project the way the original is supported and maintained?
• Can you know that?

What other choices do you have?

• Find a different work-around
• Find a different project that does what you need

One other point, in all the examples I can easily think of successful public forks are started by whole teams, who split off from the main project as a group. At least that gives each of them support from the others, and some reassurance that their vision for the project is not insane! If you were trying to fork an existing project as a one person band, that definitely wouldn't apply!

That said, the origin of the vast majority of open source software is a one person band; writing something that they want to use, then offering it back to the community.

So I guess, if you're just crazy enough, you could try that! ;)