How can I mitigate or avoid clashes with project maintainers over my bug report(s)?

Question

We keep hearing about the ungrateful job of OSS maintainers and the arrogant users with a huge sense of entitlement demanding slave work for free.

While I do sympathise with this sentiment, there are 2 cases from my recent past that I may have been one of the jerks. Yet, when I look back, I can't see what I would have done differently, other than not engage with this product.

In these cases, what could I have done to avoid or de-escalate the conflicts? Is there a better way to think about the mind (and schedule) of a project maintainer to help my approaches be received more favorably?

Case 1:

A company is providing a hosted version of their static analysis tool gratis for OSS. The documentation is scarce and the instructions are not working for my project. I spend a few evenings trying things and finally send to the support email address a detailed summary of the problem and what I have done so far, plus link to live project, asking for help. I don't get any response.

Few weeks later, I post the question on Stack Overflow. A developer from the said company replies within a day or two, and after few days of back and forth, we resolve the issue. Turns out there were a number of undocumented "known issues" (a.k.a. "you are doing it wrong") and a few easy changes that would have prevented my problem.

I summarize the conversation and recap the factors that led me astray, suggesting that they get fixed or featured prominently in the docs. Around this time a person who is actually working on the OSS Support for the said product joins the conversation, rejects all feedback and starts behaving indignantly after I make a note that they are late to the party and haven't contributed much to the solution.

Then we exchange a few comments on how I am not the only user and I can't expect special attention, while I counter with "I am the only user that has documented in public the root cause of the problem and the solution" (I saw a number of people on SO had the same problem, but there was only one half-assed solution, with major hole in it.)

In the end, all parties go away disgusted. I only wanted to be helpful -- what went wrong here?

Case 2:

Another company, another tool, integrating with a build tool I use. All of a sudden integration breaks because of a third party thing. I fix it by doing it right and submit them a snippet for including in the readme. They demand that I actually do the change and do a pull request. I do. They request I fix my readme pull request. I see no value in this back and forth and close the pull request.

Same company, few months later - I find a trivial bug. File an issue with line-number and description of the fix. They suggest a pull request. I counter that for such a trivial change I don't see the point and I am not going to spend time on it. They downvote the comment (assume they are offended), but fix the bug (yay!).

--

So, what would you think is the right course of action in these 2 situations? I want to make the world a better place, I am prepared to do some work, but I appreciate appreciation and don't like wasting my time.

Answer 1

There are at least two competing interests in how open source maintainers run their projects:

• a desire to foster and accept outside contributions
• developer bandwidth

Developers have limited time to review outside contributions, especially if the project isn't a full time job (but even if it is). Combine this with the occasional entitled user, and some open source maintainers might assume the worst about contributions until proven otherwise. Even if the users aren't being rude or entitled, they can formulate their messages or changes in a way that makes things unnecessarily hard for developers.

Consider the Linux kernel, which is extremely strict in what they require of patches and pull requests, and failure to meet those standards is not kindly received. They have enough activity (and busy enough devs) that they would rather create compliance-by-fire than waste time coddling everyone learning to submit feedback.

Case #1

Interpersonal exchanges can be quite difficult over text, especially when submitting critical feedback. Consider that the maintainers may be bombarded by requests far ruder than yours, and if you don't take pains to demonstrate politeness, it's very easy to assume the worst whenever interacting with anyone who has a complaint.

Yes, it would might be in their best interests to neutrally collect feedback from anyone who has any to offer, but obviously they didn't do that in this case. Consider also that they may have enough fully-formed contributions for their consideration coming in to fully utilize their development bandwidth, so that a suggestion or bug report without a complete code or documentation change simply doesn't merit much consideration.

Is your information about usability a net gain for the project? Of course. But it's a message that, like it or not, comes with an implicit work order: "This needs to get done." If you don't immediately follow this up with an offer to do the work yourself, it's easy for a developer to take this the wrong way. In particular, if your feedback is not especially concrete ("It should be more clear that in order to do X you need to click buttons Y and Z first" -- it should be made more clear how?) then your message places the onus of figuring out how to make the fix on the developer.

Your incomplete contribution does provide value to the project, but how you present even a very helpful contribution can provoke a bad reaction. Every maintainer is different, but in the future, you could approach the act of giving usability advice with a greater awareness that you're essentially creating heaping new work onto the developers.

Case #2

Case #2 is different from #1: for #2, there are technical and procedural reasons why they require a pull request. If a project has a protocol of accepting outside changes via pull request, then not using a pull request is about as frustrating as submitting code that doesn't conform to a project's coding standards. That is to say, it's still useful, but done in a wrong enough way that it ties up developer time -- and the entire point of the policy is to save developer time.

Pull requests are valuable for tracking statistics about outside contributions (size, frequency, how often they are accepted vs. rejected) as well as providing a standard platform for the internal team to agree on whether to accept each outside change. If a project asks you to use a pull request, then you should either do it, or be prepared for your contribution to be treated as less valuable, just like a contribution that ignores code format standards.

To put it another way: you think it would have been trivial for the developer to take the description of your change and implement it. If that's so, then you could do it yourself. You might point out that the developer could have implemented the fix faster than you could have learned to formulate a pull request. However, the developer isn't looking at this from a cold utilitarian perspective about how to minimize net effort between the two of you. The developer just sees something that you could have done yourself and didn't. (Also, taking the term to learn and do things the right way makes you a more valuable contributor in the future, so you could view this insistence on doing things the right way as an investment in you as a project contributor.)