The Minimum Viable Pull-request

Have you noticed? 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

Ok, so you have an idea to contribute to a new open source project. The naive approach would be to fork the project, write the feature, propose it, done.

Well no, the lone cowboy approach is a recipe for frustration!

Among the things that could happen:

• What you implemented was already there actually.
• The project is not maintained anymore.
• The maintainer is not interested, he has different goals than you.
• You should have implemented things differently.
• 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 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 released gradle-kotlin-dsl-libs which solves a common developer pain point (managing dependencies) for a lot of projects (those that build with Gradle) in a way that is mostly generic and automatic (apply my plugin, let it write code alone, use it, done).

This had an interesting side effect: I was suddenly able to contribute pull requests to a wide range of projects. So I did. It was a bit awkward 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. Taking a hint from the Lean Startup movement, think of your pull request as an MVP:

• Do only the amount of work that is needed to clearly communicate your idea
• Focus on opening early the discussion with the maintainers of the project.

This has worked really well for me. I learned much more quickly who was interested in my contribution and who was not. If they were not, it was fine, I hadn't invest a huge amount of time in vain. So I was not secretly mad at them. When they were interested, it was much more rewarding to put the time in the contribution, knowing it will not be in vain!

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. Nope. Your job is to make it easy for the maintainer to guide you. That includes doing less code but also doing more communication than we usually do.

Explain your use case, why you want to do that in the first place. Get some early feedback on HOW to implement that feature. Look how the CI is configured. Read the CONTRIBUTING.md file. Most importantly, obtain the permission for doing the change before you actually spend the time on it. Bonus point if you can do all of briefly.

How?

No rules here, you could simply open an issue before starting a pull request.

What I ended up doing was adding my plugin to the Gradle build and commit the generated code, but not actually modifying the existing build before I had (or not!) the permission to do so. Example: CatchUp!132

Another great strategy I've used in the past is to add a failing test to the code base

In the same spirit, you could edit the README (or some other documentation files) with the changes you intend to implement.

Actually, at that point, I would be glad to hear from you. What are the common frustrations when you have when you contribute your first pull request to a project? And how do you overcome them?