Proposal: a controlled vocabulary for attitudes towards pull-requests, forks and bug-reports

Yesterday I read Just Say No, a post by Jeff Geerling who maintains a bunch of popular devops project on GitHub. His position, which I am totally sympathetic to, is that maintaining a project is a lot of hard and mostly uncompensated work, and so:

That pull request that’s 100 lines and’ll take you an hour to review? No.

That issue that’s requesting you to pull your project just in a slightly different direction? No.

That little opportunity that you’ve been waiting for but you just know you can’t do right now? No.

Again, I am sympathetic. I agree, mostly. Yet at the same time, I hate to imagine being the guy who spent multiple days on a PR to something of real value, only to have it insta-rejected with “Sorry, I don’t have time to review this”.

I think knowing in advance that that’s the deal would make a big difference. But how can you tell? Not many projects have big banners on their home pages saying “I WILL REJECT YOUR PRs AND EAT YOUR CHILDREN”, so you don’t know to avoid investing a lot of time in developing for them.

But what if projects could say that? Simply, politely, and explicitly?

What I have in mind is a short, simple set of contributor statements that a project could make, in the spirit of the Creative Commons licenses, which could be expressed in a human-readable form for potential contributors to read, and also in a machine-readable form that could be used in contexts like Node package files or Maven project POM files.

What should be in such a statement? Well, there are other ways, besides pull requests, where project owners that vary in how like potential contributors to interact with their projects. For example, Geerling goes on to say:

That’s why we choose open source licenses. […] I do that because I encourage people to fork my projects.

If they’re angry their feature that’s critical to their business isn’t merged yet? Well, fork it!

Which is a perfectly good attitude, but not one shared by all project maintainers. So we’d want a way to talk about this, too.

And Geerling doesn’t mention bug reports, but this is another area where maintainers differ. Some actively welcome, some grudgingly accept them, and some would prefer that they not be filed at all (and may even turn off the bug tracker completely).

Again, all these attitudes are perfectly reasonable: when someone has put in the work to create and maintain a project (or take over maintenance for a project that someone else created), they don’t for that reason owe anything to anyone. All I want is a simple way for them to communicate what their attitudes are.

The proposal

The statement consists of the constant string CA (for Contribution Attitude) followed by one to three clauses, joined by hyphens.

Each clause consists of two capital letters: the first indicating a type of contribution and the second indicating the maintainer’s attitude to contributions of that type.

The contributions are pull-requests (indicated by P), forks (F) or bug-reports (B). (When multiple clauses are present, they should canonically be expressed in the order P, F, B.)

The attitudes are that contributions of the specified kind are welcomed (W), tolerated (T) or unwelcome (U). (We can’t use “P” for prohibited, because you can’t in general prevent people from doing things. If someone really wants to fork your GitHub project, all you can do is tell them you’d rather they didn’t.)

So for example, Jeff Geerling’s CA string for some of his projects might be CA PU-FW-BT, meaning that pull-requests are typically unwelcome — perhaps you should talk to him before starting development — forking is welcome, and bug-reports can be filed but no promises are made that they will be attended to.

The human-readable version of this string would be “Contribution attitude: pull-requests unwelcome, forking welcome, bug-reports tolerated” — just as the human-readable version of the license CC By-NC-ND is “Creative Commons attribution, non-commercial, no derivatives”.

Possible tweaks

Might we need to refer to other kinds of contributions than pull-requests, forks and bug-reports? For example, perhaps documentation (D) should be considered separate from pull-requests that change code?

Is P, F, B a good canonical ordering for the clauses?

Do we need to break down attitudes to a finer grain than the three options given above (welcome, tolerated, unwelcome)? For example, should we include ask-first (A)? I am wary of adding too many categories, otherwise the scheme becomes too cumbersome to use, like too many over-comprehensive ontologies I have seen.

Anything else?



One response to “Proposal: a controlled vocabulary for attitudes towards pull-requests, forks and bug-reports

  1. A month later …

    Wow. No-one cares about this.

    Oh well.

Leave a Reply

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

You are commenting using your 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

This site uses Akismet to reduce spam. Learn how your comment data is processed.