OSS Rules of Engagement

After two posts to a reaction of a comment on feedback I had for the Git installer, I thought it was pertinent to share my thoughts on OSS rules of engagement. Scott Chacon left a comment along the lines of “your time spent complaining is better directed at submitting a pull request”. Which, as an OSS developer and project maintainer, I agree up to a point, until that reaction discourages feedback.

I understand how daunting it can be to contribute to an unfamiliar project, especially if you recognize that the people most familiar with the codebase would take a lot less time to do so, and probably do it “right” in the first place. I also understand how frustrating it can be to have large, visible OSS project where the number of people complaining/giving feedback far dwarfs the number of people actually contributing.

So what are the rules of OSS engagement for me?

1. Un-actionable complaints will largely be ignored

Mostly because I don’t have too much time to figure out what you want. I generally will respond with prodding, but unless you respond back, I won’t have anything actionable to address. Having an example of the alternative is generally the minimal bar here.

2. Feedback is encouraged. Example client code even better

As an OSS developer maintaining libraries, I often get feedback of “Can it do XYZ?”. Sometimes the answer is No, but I would like to see what your vision of how it should behave.

What should the methods be called? What does the configuration look like? What’s an example of the behavior you’re envisioning?

I don’t even care if the code compiles – just show me an example of what you’re thinking.

3. Unit tests for bugs encouraged, but not required

I just really need code to reproduce the bug. A report of a bug with zero code is much harder to reproduce, and much less likely to get fixed.

If you want to up your odds of getting a bug fixed, the more code I get demonstrating the problem, the better.

4. The more actionable the feedback, the more likely it gets integrated.

Pull requests are at the top end of the “actionable feedback” scale. An email reporting a bug with no code as at the low end. The more actionable the feedback I receive, the more likely I will have the time/energy to respond to the feedback.

However, I won’t turn people away for not giving me a pull request. I encourage it, and often point folks to try, especially if they want to “up the odds”.

I might encourage you to send me a pull request, but I’ll never disparage you for not sending me one.

About Jimmy Bogard

I'm a technical architect with Headspring in Austin, TX. I focus on DDD, distributed systems, and any other acronym-centric design/architecture/methodology. I created AutoMapper and am a co-author of the ASP.NET MVC in Action books.
This entry was posted in OSS. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Anonymous

    I put several projects up on GitHub for the pure purpose of sharing my code. I don’t intend them to be fully supported or “have an implied warranty.” That said, I like getting feedback on them when people use them and while I don’t have much time to work on them after I post them, I do help people out.

    Two people within the last week have sent me questions about my API for interacting with GiantBomb. I made it specifically for myself but I posted it to GH in case other people might benefit. I specifically said that I didn’t plan to add any more features since I only used what I needed but I’d gladly accept pull requests.

    Anyway, these two users asked me if my API did this and that and what not; I responded and helped them both out. One of them wanted to add a field and I told them how they could do that and about some caveats I knew about when I made the API. It was a cool experience, I guess, since I didn’t really set out to be “an OSS manager” just more like, hey, here’s some code, have fun! To hear someone one say “Thanks you really made my life easier” makes it all worth it.

    For me, the issue is that I like to share (most of) my code because I think it might help someone who had a similar problem or might make someone’s life a little bit easier. I don’t really work too much on them after I use them in my own project. If I did, I wouldn’t have time for my own personal projects that these are born out of.

    I do think for big projects like Nuget the biggest barrier to me trying to fork and contribute is simply the time it takes to understand the codebase. I had mentioned to the devs that it would be really nice to add diff/merge capability when upgrading/installing packages. They said it would be but it wasn’t in the plan in the near future. That makes sense; if I really want it (and we kind of do) we should try and come up with a proof of concept. If I didn’t have anything else to work on, I definitely would… but like I said, it takes a lot of effort for someone unfamiliar with a codebase, even a small one, to get comfortable enough (or confident enough) to contribute. I’m not saying that Nuget owes me this feature because I don’t have time to contribute it, I’m saying I want to contribute it but I wish I had the time/capability to do it.

    I think many projects, even Nuget, go to great lengths to help people understand how to contribute. Even then, it’s just simply a hard thing to do. People code differently, people’s level of understanding varies greatly, etc. etc.

    Anyway… good post :)

  • Jimmy, your post just sparked something I’ve seen on many occasions. It was just the straw that broke the camels back that made me write the post. How that ended up being interpreted as me saying Enterprise devs are stupid or OSS is exclusively for money and fame (despite my sarcasm of reference to micro-celebrity) is beyond me. However, never too late to learn.

    • Anonymous

      I didn’t take your post that way – I realized it wasn’t meant for all OSS devs. But I was also prepped for the idea that in quite a few areas of OSS, people have all kinds of reasons to do it and many times multiple reasons…

      • Rob, I mentioned numerous benefits, starting by learning. That was somehow turned around into “The only benefits is fame and fortune”. I mentioned Enterprise and MS shops as an anecdote and later say not everybody needs to know everyone else’s source control and unit testing framework (i.e. one works with SVN another with Hg). That was interpreted as “Enterprise devs don’t know source control”. As I said, maybe I should learn better ways to express myself. 

  • Samuel Langlois

    I like your attitude towards OSS feedback. Sure, you can very strongly encourage your users to send a pull request, or unit test reproducing a bug, but I don’t think you should dismiss a user’s feedback if he doesn’t do this. Some users might not be familiar enough with the source code or technologies (source control, github, etc.) to do so, but might have valid and interesting feedback.

    Also, everyone’s time is limited and they can’t contribute to every open source project they’re using (or trying out). Especially if they find a lot of issues with it; they will want to know what’s up with these issues before investing their time in this project. If they take some of their time to give feedback on your project, you should listen.

  • Agree!
    Every feedback is positive…