Whether commercial or Open Source, most software projects follow some sort of guidelines for ensuring smooth processes and quality outcomes. On a small team, it's easy to enforce these rules informally, but to scale up, tools like automated builds and coding-standards checkers are indispensable.

PR.js on Github

Nowhere is this more acute than Open Source projects. The dueling objectives of keeping barriers to entry low while ensuring the quality of contributions means tools that provide automatic feedback and guidance always win over lengthy contributor guides and human review.

At Radify, we run & contribute to a number of different Open Source projects and, while we have many tools for validating the quality the code itself, we've found ourselves having to repeatedly coach would-be contributors on how that code should be submitted. Things like:

  • which branch a given change should be submitted to
  • that commits for a single, logical change should be squashed
  • details a pull request should include

And everybody's favorite:

  • how to format commit messages

As feedback cycles get longer and further away from a contributor, the more likely they are to become discouraged and give up entirely, a loss of unknown potential: could that person have become your next top bug crusher, doc writer, or issue triager?

We looked around for ways to automate this, but found that the list of existing solutions was... anemic... at best. So, we went ahead and made one.

Enter PR.js. It validates your project's PRs against a(n optionally configurable) set of rules. It requires no signup, no setup, and no changes to your project. It has built-in rules for most of the above, but you can easily roll your own rules for anything you like. Internally, we'll be able to use it for things like validating embedded metadata in commit messages, ensuring user-facing features have a screenshot and test script, and that branches are correctly identified for demo deployment.

We now have immediate, linkable, browseable feedback for all of our Open Source projects, and we're working on further integration with GitHub to manage private projects, as well as provide feedback directly in PRs via the Build Status API.

In the wild

What kinds of PR workflow rules do you use on your OS project or dev team? Is this something you'd use? Let us know, and if so, feel free to fork and contribute your own rules.