Regarding contribution to open source projects
The following scenario has been played out countless times, by a large number of [first time] contributors, to a large number of OSS projects:
- Find OSS project we love
- Attempt to navigate [source of] project
- Find this confusing
- Decide that there needs to be some "cleanup"
- Start making pull requests to cleanup [the source code]
- Pull requests are ignored, refused, or argued against
- Dismay
Most of the time, we quickly get a feel for the kind of pull requests that will be accepted, everybody moves on ...
But I wonder if they move on before putting any effort into explaining why this type of contribution is not always met with jumps for joy ...
I wonder if we can't say some things about all open source projects, that might guide new contributors to making the kind of contributions that have a good chance of being accepted. Perhaps, more importantly, making contributions in such a way that the (new) contributor becomes an asset for the project.
Communications
Communicating with a group of people at once, often about complicated technical matters, is not an easy thing, no matter the calibre of the programmer.
The following sections will seek to provide guidance regarding communications with existing contributing members of a project.
Signal to Noise
Contributing members of a project generally have a steady signal to noise ratio, that's to say, on a yearly (or quarterly, whatever) basis, they make about the same amount of noise, as they do contribute to progress. The ratio varies, depending on the contributor, but steadiness makes for normality, so typically we all get used to even the loudest contributors.
New contributors on the other hand, if nothing else than by virtue of the fact that they have more questions to ask than anybody else, tend to have an unsteady signal to noise ratio, and because the entities you are dealing with are human, this simply annoys them.
The people being annoyed, they very well remember being just as annoying as you are being, so don't take it to heart ...
But maybe there are some things you can do as a new contributor to try and keep a steady ratio ...
Mental Metabolism
New contributors are in learning mode, no matter how familiar they are with the subject matter, language, or patterns used in the project.
In learning mode, we tend to ask as many questions as occur to us, and seek answers as quickly as possible.
This tends to result in noisy communications: A thing to consider is that for every communication you might be sending notification to every subscriber to the medium, be it a github repository, mailing list, forum, or whatever.
Unless you are providing a patch for a life support system and lives are in danger, there is absolutely nothing that can't wait 24 hours.
By waiting a day between your communications, you are affording other contributors time to have their say (and possibly answer questions before you have had the opportunity to ask them). You are also providing yourself much more thinking time, possibly increasing the quality of your communication, and certainly reducing noise.
O(1) Communications
New contributions tend to garner responses or input from several sources, and having waited 24 hours since your last communication, you might have a pile of communications to respond to.
You can further reduce noise levels by responding to everybody at once, don't be afraid to tag people, segment, or otherwise format communications to achieve this.
Once you have the response for the day written out, you might try to compress it by finding overlap, you might even try to preempt what will happen next and try to provide answers to the coming questions in advance.
Source of Truth
Healthy projects tend to develop experts that don't necessarily have any involvement in contributing directly to the project: There are many many more Ruby experts than there are Ruby contributors, mutatis mutandis, the same is true for any project you like. These experts tend to be available outside of official channels, sometimes in groups, sometimes even in realtime.
Let opening an issue, pull request, or otherwise sending "official" communications be a last resort. Realise that the project you are dealing with is never the only source of truth, and that by finding other sources you can further and greatly reduce your noise level.
Choosing Battles
Be ready to gracefully walk away from any contribution or idea you had, be ready before you send your first communication to just be wrong.
Begin wrong is fine, that's how we learn ... It's sometimes hard to see that in the moment though, and find ourselves fighting tooth and nail for what we think is correct.
Realise that your first contributions are not likely to be your most important. You're dealing with humans, and if you make a lot of noise at an early stage, your voice will carry less weight later on.
The Pull Request
Whether communication should precede a pull request is sometimes determined by the rules of the project.
If you are making this decision, then consider how well the project deals with and responds to pull requests.
If there seems to be evidence that the project struggles to deal with pull requests and if there is a channel for communications other than the channel opened with the pull request, consider communicating before opening a pull request.
Cost and Value
A pull request must result in a net gain for the project.
There are so many ways to achieve a gain that it would be pointless to try to enumerate them. The most common path to a loss is as a result of miscalculation of cost.
As the author of the pull request, you might want to say that the cost associated is whatever it cost you to write the pull request.
But that's not the only cost associated, here's a better starting place for a list of costs:
- The time it took you to write the pull request
- The time it's going to take someone, or some people to review the pull request
- The time it's going to take someone to merge the pull request
- The time it's going to take someone, or some people to document your changes
- The time it's going to cost anyone familiar with whatever you are changing
All of this, before the correctness of the pull request even matters.
Of course, correctness does matter, as well as the content of the pull request ... In some cases, a pull request will have an ongoing, or ongoing costs associated with it.
Generally, if that ongoing cost is going to be incurred by humans we call it technical debt.
Generally, if that ongoing cost is going to be incurred by the machines executing the code, we refer to it as implementation complexity, or some other fancy term.
These costs hard to quantify, and there is likely disparity between your method of calculating these costs and the methods of existing contributors.
The value your pull request provides must exceed the sum of these costs (as calculated by existing contributors) to be worthwhile, and you should be utterly confident that it does that before you open the pull request.
Final Words
Don't let anything, including the words herein, deter you from your goal of becoming a contributor.
Achieving your goal will be your reward ...
