What are “commit props”?

As I talk to people outside of WordPress about open source software processes, one thing that always catches attention and gets positive feedback is our method of giving credit to people who contribute to a given release. There are a ton of ways you can contribute to WordPress-the-project, but the thing I deal with in particular is the core software, which runs on release-based cycles. There are commit message guidelines (originally authored by me!), which start with:

Props should be given to all those who contributed to the final commit, whether through patches, refreshed patches, code suggested otherwise, design, writing, user testing, or other significant investments of time and effort.

So what are props? Well, in a commit message you might see something like:

props boonebgorges, melchoyce, helen

What this means is that the person who committed the code has compiled a list of all the people who contributed to that changeset, not merely in terms of code, but any meaningful effort that moves the software forward. Some of this terminology is because we use Subversion and Trac, so to frame it in GitHub-type workflows, this would roughly be the equivalent of doing a squash merge of a PR and adding that line so as not to lose attribution that you might otherwise get with a regular merge. That latter type of attribution is limited to people who’ve managed their way through version control and committed something, typically code. There are limited opportunities for equally critical participants in disciplines like design and writing to get the same kind of credit.

GitHub has a Co-authored-by trailer that makes it possible to give multiple attributions on a commit that is reflected in GitHub profiles. This is really cool! And I think it needs to go further 🙂 It’s a very tedious process to add these trailers, typing them out and gathering names and email addresses. It should be easier for maintainers to be liberal in giving credit to other people who’ve helped along the way – a specific line prefix with a comma-separated list of usernames seems like it would work there as well (in WordPress, commit messages are parsed for those lines to generate the list of credits for a release). There’s still a bit of an issue of giving those props when your commits are very atomic – at what point in all that code do you stop to give a designer credit for coming up with this thing for you to even be coding in the first place? But that starts getting into why I believe in squash merges and that’s better saved for another time.

Attracting and retaining a diverse contributor base is critical to the long-term health of open source projects, especially ones with large user bases, large code bases, and a bunch of different interfaces. Not only is technically being able to give credit an important component of that, but fostering that mindset of “people who write detailed reproduction steps are just as helpful in fixing a bug as somebody who submits some code” has really helped shape valuable maintainers and contributors alike.

What are “commit props”?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s