Rookies in the Bike Shed

Ah I'm sorry, I should have rechecked before posting this. I meant no offense.

There you see how closely I follow this story... :)

I was thinking about avoiding replying on this thread, because I can't know the motivations of the people involved, but this reply kinda takes the cake.

I was an active open source contributor and maintainer for around 6 years this past decade. I've witnessed (and sadly fervently participated in) my fair share of bike-shed discussions. Some (most?) of them quite regretfully.

I've learned something recently about APIs and frameworks, when you're the author. Something that should be obvious, but apparently isn't: your job is to make it as easy to build on as possible. Full stop. That's it. That is the number one priority. If one of your interfaces is confusing, you make it not confusing. It doesn't matter if it makes the implementation a little bit more complicated, or a little bit less beautiful and idiomatic. It does matter if it introduces a huge unacceptable performance degradation or a security issue. But that just means you need to rethink your implementation and assumptions.

Because really, the user of your software is all that matters.

You can make all sorts of stupid arguments, arguments that I myself have made in the past:

  * I write this software for me, not for you.  Be happy that I've chosen to share it with you so you can benefit too.
  * Maintainability is more important.
  * Implementation elegance is more important.
  * Following common idioms is more important.
  * It's documented, so even if it's not 100% straightforward, it's ok.
  * If you don't like it, fork it.

No. I don't care. At all. Once you make your code public in the open source world, it's not yours anymore. It belongs to everyone. Suggesting any of the above is just selfish, egotistical, and irresponsible to your users. This is the real world here, not some idealized theoretical academic playground. People use your software to get work done. People use your software to avoid having to reinvent the wheel every time they come across a similar problem. People use your software because it saves them time. Oh wait: except when behavior is changed for no good reason, and now they have to audit tens of thousands of lines of code to make sure everything still works. It's utterly unnecessary to force people to do this.

I've been sorely tempted any number of times to stick to my guns, believing more in the principle of the thing than in the practical effects my decision would have on my users. And I'm sad to say that many times I made what I now know to be the wrong decision.

The closing of the initial pull request might be forgivable. I disagree with it, but hey, it's not the end of the world, and there's certainly precedent for that behavior. Sure, the change that introduced that behavior is pretty questionable, but... ok, let's leave it be. But then we have another developer who commits a change that "fixes" the behavior in a manner that looks elegant and readable and maintainable. And you revert it. Why? Because you feel it sends the wrong "message". Because it might make people believe that all predicate methods return boolean singletons. Which is nothing more than convoluted logic used to reinforce your own opinion.

But ok, ok. We're all human. And I could certainly argue that it was rude of the other guy to make that commit without consulting you first. (Assuming he didn't, I actually do believe it was pretty rude of him to do that.)

And then there's the final straw: someone submits a pull request to augment the documentation to make it clear what the method actually returns. And you reject it. Ok, you don't want so much information about the internal implementation in the docs. Gotcha. But you can still make the docs clearer without leaking that info. (Or, hell, you could just, y'know... not leak the implementation out through the API call itself.) All credibility lost now. The crap about variable-width vs. fixed-width font usage in docs is just semantic masturbation. You are not making things clear for your users. That is a problem. Instead of fixing it, you dismiss people who try to help you.

Is this particular issue a bike-shed moment? Yeah, probably. The return value of xml_http_reqeust? isn't really what I care about. I'm sure there are plenty of other predicates in Rails that behave similarly. The issue here is the message this sends: "I care more about writing idiomatic ruby than I care about making my users' lives easier". Which is ridiculous when you consider that the entire purpose of Rails is to make webapp developers' lives easier.

> That if you're willing to redo Rails because a predicate method...

I wasn't clear. My mistake. The issue isn't one of a predicate method, but rather, overall approach. If Rails doesn't work the way you want, you don't whine and complain it doesn't work. You either accept it, or move on and do something better.

The if the attitude demonstrated here is something you can't work with, you move on. It's not just this issue, but every issue like it as well.

I agree with the premise of the post (bike shedding is pointless); however, if you need a garage and not a bike shed, trying to get people who want that bike shed and are building that bike shed to instead build a garage, your better off moving on.

Maybe they are just trying to optimize for pedantry.

I agree this is a good approach for any open source project leader to have.

It's valuable to let rookies argue small debates so they can learn the ropes and get a feel for the community; it's even more valuable for the veterans and leadership to make decisions, set priorities, and maintain focus on what's important. Both are necessary to grow and sustain an open community project. You bring people in and get them engaged whilst reinforcing what the project is focused on, its tone, style, and mission.

Making a decision civilly, whether everyone agrees or not, is very reassuring to newcomers and oldtimers alike. It proves that the community is fun and worthwhile.