June 20, 2014
  • All
  • Ionic
  • Open Source

The Art of a Successful Pull Request

Max Lynch


When we started Ionic we didn’t have much experience managing popular open source projects. So when the project started taking off, gaining 6600 stars and 90 contributors submitting hundreds of pull requests from countries all over the world in just 6 short months, we had to learn quickly how to successfully manage a growing open source project.

One crucial aspect of open source software development is the Pull Request. Pull requests make it possible to accept changes and improvements from the community without dealing with the complicated nature of committer privileges or growing a monolithic development team.

The problem with pull requests is that their creation is unmanaged. Meaning PRs often end up with code styles and implementation details that don’t fit with the standards or goals of the main project. Since every open source project relies on its community to improve the project through code contributions, enabling and encouraging pull requests is crucial.

Here are some steps to successfully creating pull requests that get merged in your favorite open source project:

One commit, one change

A good pull request is easy to reason about. It has just one commit, and changes as few things as possible.

If a pull request addresses multiple issues or is treated as a “work in progress” PR, then it will be difficult to verify the PR is self-contained and does not cause unintended issues.

Example of a good one: https://github.com/driftyco/ionic/pull/1478

Example of a not so good one: https://github.com/driftyco/ionic/pull/654

Scratch everyone’s itch

Don’t submit PRs that are so limited in scope that they wouldn’t be useful to the entire community. Examples are extremely custom UI elements (using Ionic as an example), to functionality or API changes to better fit your application.

Label WIP PRs as such

Work-in-progress PRs are really useful. Done well, they provoke discussion, make it easy to track progress, and invite review from the community.

However, WIP PRs are more appropriate for mandated work that has already been agreed upon by the project owners.

Max Lynch