The Minimum Viable Pull-request
Contributing to an open-source project doesn’t have to be frustrating.
🇰🇷 A Korean translation is available🇰🇷 thanks to Wind Sekirun
Have you ever noticed that while many of us do a few open source contributions, some happy few somehow manage to contribute ten or hundreds times more in the same 24 hours per day?
Are they the Rock-Star Ninja Developers that our recruiter friends keep talking about? Or maybe they just figured out how to contribute more effectively.
The problem
You have an idea to contribute to a new open source project? It’s open-source so you can do whatever you like with it, right? So just fork the project, write the feature, propose it, done.
Done? No!
This lone cowboy approach is a recipe for frustration!
Among the things that could happen:
- The project is not maintained anymore.
- The maintainer is not interested, he has different goals than you.
- There was a 5 times easier way to implement the same thing.
- What you implemented was already there actually.
- You didn’t follow the indications inside
CONTRIBUTING.md. - You didn’t notice the CI checks that ensure that the test suite is still running correctly. Sure enough, the build is marked as failed.
- You didn’t respect the various naming and code conventions of the project.
- After a few such iterations, weeks have passed since you forked and master is a huge merge conflict before you.
- …Insert your anecdotes here…
I recently contributed to multiple Open-Source projects. I was a bit awkward at it at first but I got better with practice. The main takeaway I would like to share with you is what I would call the Minimum Viable Pull-request.
The WIP pull-request
In case you don’t know, the WIP pull-request is an established practice and convention to improve the communication inside a developer team:
- Open a pull request when you start working on a feature or a bug-fix, not when it’s ready.
- Name your pull-request
WIP: XXX. This convention tells others that you are working on it and are open for early feedback. - When you are almost ready, remove the
WIP:prefix, announcing that you now need a final review.
MVP + WIP = Minimum Viable Pull-request
There is a core problem that makes it hard to do your first contribution to an open-source project: you don’t know the project. You don’t know its people. You don’t know its codebase, its rules, its context. And the maintainers don’t know you. You are also in exploration mode.
My advice: think of your (WIP) pull request as a MVP
The MVP concept comes from the Lean Startup movement. Its goal is to accelerate learning in an environment with a lot of unknowns. Here is how we can take inspiration from this approach.
Rule 1: Do only the amount of work that is needed to clearly communicate your idea.
Rule 2: Focus on opening the discussion with the maintainers ASAP.
(Conveniently, MVP is also the right acronym for Minimum Viable Pull-request so we don’t have to learn a new acronym!)
Minimum Viable
A caveat here: Good developers, being lazy by virtue, tend to gladly focus on the Minimum (“Hey, doing less work is better!”) and skip the Viable part.
Not quite! Your job is to make it easy for the maintainer to guide you. That includes doing less code but also doing more communication than usual.
- Explain your use case, why you want to do that change in the first place.
- Ask for early feedback on how to implement that feature.
- Read the CONTRIBUTING.md file.
- Have a look at other’s people pull-request to understand how this project works. Look how the CI is configured.
- Most importantly, obtain the permission for working on the change before you actually spend the time on it.
- Bonus point if you can do all of this briefly :P
How?
No rules here, you could simply open an issue before starting a pull request.
A great strategy I’ve used in the past is to add a failing test to the code base
A similar idea would be to edit the project’s documentation with the changes you intend to implement.
Or consider the experience that leads me to write this article. I have just released a Gradle plugin that solves the pain points I had with dependencies management.
I was suddenly able to potentially contribute to a lot of projects. Potentially. But lots of projects are just fine with their current solution. How to find out which? I opened pull-requests where I applied and run my plugin, then updated the build as little as necessary to show what my solution brings to the table.
This MVP approach has been great for me. I learned quickly who was interested and who was not. When they were not interested, I had not invested a huge amount of time in vain, so I was not secretly mad at the maintainers! When they were interested, it was much more rewarding to put the time and the effort in my contribution, knowing it will not be in vain!
Learned something? Click the 👏 to say “thanks!” and help others find this article.
Have some insights to share? I would be glad to hear about it in the comments!
