If I post a bug report like "when I run command X, there's a crash", how many OSS authors get annoyed?
If anyone gets annoyed at that, this is a sign they need to take a break from the project (or from the bug database), not a sign that the bug reporter needs to do anything differently.
There are some projects I've submitted issues for without such excessively fluffy language, and the maintainer has responded very negatively. I hate this, because it makes the maintainer look like a cantankerous prick, and it also puts me off using what might be a great project (and of course others will read it to).
IME, if I'm not familiar with the maintainers' temperament, I'm most successful using something like this template:
"Hi! First let me say how much I appreciate this library, it really helps with X.
I've found what I believe is a bug, whereby X (provide logs, stack trace, whatever is relevant).
You can reproduce this by X (provide repro steps or code snippet as appropriate)."
For projects I'm familiar with, things can be more business-like and to the point, and I can also offer to send a PR.
I like your approach. As a maintainer of small projects with very few users I'm not offended by business-like bug reports. But it's very nice to hear someone is actually grateful for my software. (You only need one arrogant asshole demanding support to feel like your software is shit and maintenance is a burden.) Of course you only need to make a good first impression once.
This approach will also help if another part of your message comes off as arrogant. That can happen when English is not your native language.
Meanwhile this kind of dancing around the issue will piss me off, though I don't usually respond so.
If there's a bug, tell me what happened, what you expected, what your config/environment looks like, and if it's a library a minimal code example that triggers the bug.
I don't need to hear about how your grandmother's favorite chili recipe saved your uncle's best friend's life when he was trapped in the Siberian wilderness after going on the run from the Malaysian government. Just tell me how to make the damn chili.
If you like using my software and it makes your life better in some way, I absolutely want to hear that - it will help keep me motivated the next time working on it feels like a chore.
We love hearing about that in the D forums. But in bug database submissions, just the facts, Ma'am.
P.S. I have several letters from Empire users who reported that the game caused them to flunk out of college and/or get divorced. I'm not sure if they were complimenting or complaining :-/
I think the thank you messages could be separate from the bug reports (which should be sterile and 100% tonally neutral). One possible way to separate it is to have thank you messages on twitter. It will also help promote the project, where as these messages in bug reports will get buried and lost and no one else is gonna see it.
Thank you, if I had expressed it this way I don't think I'd have riled as many feathers but this is exactly my stance. (apart from specifically Twitter)
I take your point, and I wouldn't want to read through reams of frivolity either - but there really wasn't anything like that in my example; it's 1 or 2 like saying "thanks", and then my example included all of the stuff you asked for.
Yeah, there's a difference between sharing your life story and a quick thank you, and if I have to take into account people who get offended by being thanked, then I wouldn't be able to communicate at all anymore.
You can't please everyone, and erring on the side of being too polite on average has worked pretty well so far for me.
> I don't need to hear about how your grandmother's favorite chili recipe saved your uncle's best friend's life when he was trapped in the Siberian wilderness after going on the run from the Malaysian government. Just tell me how to make the damn chili.
The template given was nothing like that, at all.
Regardless, I firmly believe that this attitude is keeping many people out of the tech business, let alone open source. Society shows that niceties are wanted and work, especially by women, a demographic under-represented in most parts of tech. I also find that not showing niceties is a display of dominance and self-importance, again, something that isn't going to bring more people into tech.
I can give a pass to Linus Torvalds and those under time pressure. I doubt any of the devs here commenting on HN are able to make either of those claims.
> The template given was nothing like that, at all.
That's fair, I waded in to discuss a related pet issue and it's probably not fair to have posted the way I did.
> Regardless, I firmly believe that this attitude is keeping many people out of the tech business, let alone open source. Society shows that niceties are wanted and work, especially by women, a demographic under-represented in most parts of tech. I also find that not showing niceties is a display of dominance and self-importance, again, something that isn't going to bring more people into tech.
Let's start with the part where I said "though I don't usually respond so." It irritates me, but I tolerate it because my goal is to help people.
As for not having space for stories/niceties driving away women, I don't walk into the emergency room and think "man, this is a sausage fest". Usually there are vastly more women working there than men. Yet from discussions I've had with people who work in that area this is a common frustration there as well.
"You're bleeding, I don't need to hear about how depressed you've been since your grades are poor, fast forward to the part where you slipped while drunk and fell onto a broken beer bottle so I know what kind of treatment to administer." That's a made up example but is actually less ridiculous than the actual examples I've heard.
I'm not saying to leave out relevant details, but when you're bleeding or have broken bones or your left side is going numb, just tell the doctor the facts, as concisely and as clearly as you can.
If you want to tell stories, go to your primary doctor when you're not facing an emergency. Or, and this is not dismissive so please don't interpret it as such, go to a therapist, or a councilor.
A bug report on an issue tracker is obviously not life threatening in the vast vast majority of cases, but it's the same idea. It's where you go when things are broken, so tell me what's broken and the relevant context.
If you want to give thanks or talk about what you like or how you get value from the project or whatever, there are other venues for that and I encourage you to use them. Or put it at the end of the issue thread after the problem is at least identified. I've never been upset at someone for clearly expressing the problem and then saying thanks when I fix or acknowledge it.
EDIT:
> I also find that not showing niceties is a display of dominance and self-importance, again, something that isn't going to bring more people into tech.
It takes some serious mental gymnastics to turn a focus on helping people as quickly as possible into "a display of dominance and self-importance". I'm specifically asking people to not kiss my ass about "how much this project helped them during a dark time in their life" or whatever so I can get to the root of the problem they're encountering and resolve it.
It's incredibly bad faith to claim that trying to be efficient with my volunteered time so I can help as many people as possible is an attempt to dominate the people I'm helping. Frankly this sentence makes me question your motives here. Had I taken this sentence in earlier I wouldn't have responded to your post at all.
Yes, get rid of the niceties when you're under the kind of time pressure and situation you might find in an emergency room and you're bleeding.
Otherwise, use them. Does your development time resemble the conditions above, or is it more like you sitting at a keyboard in a nice room with a coffee reading comments on the internet?
As to an emergency room not looking like a sausage fest, the stats don't back you up. From [1]:
> The study's lead author, Remle P. Crowe, a research scientist at ESO – an emergency-medicine data company based in Austin, Texas – says she wasn't particularly surprised by the results, which culled data on graduates of EMS training courses as a proxy for likely diversity in the upcoming workforce. A former emergency medical technician, Crowe says the profession has long struggled to attract minorities and women, and previous studies have shown similar outcomes.
There are plenty of numbers given in the article that show low numbers of women among emergency room staff.
> Yes, get rid of the niceties when you're under the kind of time pressure and situation you might find in an emergency room and you're bleeding.
Again it's my fault, I brought up storytelling and was complaining about that. I'm not upset at the word "please" or something. Your posts keep saying niceties and my posts keep saying stories, which makes me think either you're not hearing my repeated admissions of sidetracking or you're intentionally pushing an agenda.
> > That's fair, I waded in to discuss a related pet issue and it's probably not fair to have posted the way I did.
Was my wording there.
> As to an emergency room not looking like a sausage fest, the stats don't back you up.
As I understand it emergency rooms work with EMS but most people in the emergency room are not EMS. If those stats do extend to the E.R. workers then I wonder whether my local E.R. does something different or if it's purely chance, but I'd estimate 70% female at least.
Either way the point was an analogy. Bug reports are for the bug details. There are other venues to talk about how much this leftPad library changed your life. That's all I'm trying to say.
It's very strange how in this thread maintainers who prefer ass kissing are egotistical and dominating, and maintainers who don't require ass kissing and would be more comfortable if you left it off are also egotistical and dominating. Is the message you want to convey simply that I should not volunteer my time to helping people?
This is what you responded to, this is what is being advocated.
> "Hi! First let me say how much I appreciate this library, it really helps with X.
When I, or anyone else in this thread advocates for adding a life story into a bug report or the like, then you can bring in your stories about stories and it'll be relevant.
> Is the message you want to convey simply that I should not volunteer my time to helping people?
Quite obviously not, it's that you should stop comparing yourself to those in life threatening, intensely time pressured situations and try to be more pleasant to those you're responding to, not trying to find excuses around doing so. You work in a pleasant environment, with low pressure, and are well rewarded, you definitely have the time to be well mannered.
> maintainers who prefer ass kissing are egotistical and dominating
It's not about "ass kissing" but basic respect, and if you wanted to provide an example of how not to exercise restraint and apply any semblance of etiquette, that would be a good one. Do you ever wonder why development is a "sausage fest" instead of the emergency room?
Speaking of basic respect, when someone admits to a mistake several times in a conversation and says explicitly "I waded in" and "it wasn't fair [of me]", repeatedly focusing on berating them for that mistake is not very respectful.
It shows that you are not listening to understand, but to find argumentative points. If you're truly concerned about dominating behavior that drives people away, I suggest you start with your own communication. I've been there myself, and I slip up quite often, so don't take this as judgement, only advice.
> Speaking of basic respect, when someone admits to a mistake several times in a conversation and says explicitly "I waded in" and "it wasn't fair [of me]", repeatedly focusing on berating them for that mistake is not very respectful.
We go from a grandmother's chilli recipe in an issue and end up with a comparison using bleeding patients in an ER. That's not someone apologising for a mistake and correcting, that's someone trying to wriggle around easily challenged and fantastical statements used as excuses. What next - are we airline pilots trying to save a plane with 3 failed engines while children selfishly ask for a tour of the cockpit?
I want to add, as an OSS maintainer myself, I don't put the blame for attitude solely on the kind of maintainer I mentioned. It's very common to get get users using demanding, demeaning or ungrateful language, and that type of thing does wear on you.
> There are some projects I've submitted issues for without such excessively fluffy language, and the maintainer has responded very negatively.
You are only responsible for what you say and do, not how someone else chooses to react. If you provide a bug report in good faith, and don't act entitled or snotty, you've done your part, and have behaved within the terms of the implied social contract. If the maintainer chooses to react in an unwarranted manner, that's on them, and I think that sort of bad behavior should be exposed for others to see.
Personally, as a maintainer, I find that unnecessary fluffy language makes it harder to get to the meat of the problem, and it annoys me. If you're risking a bad reaction either way, why not choose the way that's objectively the most helpful?
I think stating a bug matter-of-fact-style is fine, personally. As long as there isn't a negative tone, I don't think you need the introduction. "Tried this, expected this, got this", with a title containing a clear summary.
I've created and maintained some libraries, and I think if a library maintainer takes issue with totally neutral, fact-stating bug reports, that's entirely on them. If you're stating nothing but the technical details, there's really no implied sense of entitlement or bitterness. Maybe it comes across as cold, but it's an issue tracker, and posting issues is the point. It fits the context.
For some people their code are like their kids; precious and they can do no wrong. These tend to be a problem when bugs crop up, because bug reports are like a personal insult to them.
Personally, I've long held the view that practically all code is buggy one way or another and that many things can mean throwing code away is the best way forward, so one just shouldn't be attached to a few bytes. One should rather feel attached to the project at hand, which then naturally results in one trying to improve it, which means bug reports are GOOD and EXCELLENT because they give very clear hints were the project can be improved.
If you've got tests then you've already seen how many stupid mistakes you make, long before release. To get that far and still not have learnt enough humility to accept there may be more is quite the achievement!
Catching a bug while testing is clever. You wrote a good test.
Getting a bug report is stupid. You made a mistake, didn't catch it while testing and actually published it for others to see how stupid you are.
I see, thanks for the clarification and my apologies for assuming the worst - maybe I've come to expect the kind of hubris I thought you were displaying because, all too often, programmers actually do display it. Just the other day I had one comparing himself to a doctor in an emergency ward, heroically saving bleeding victims, because he deigns to contribute to open source. This justifies treating the writers of bug reports with disdain, of course.
> For some people their code are like their kids; precious and they can do no wrong. These tend to be a problem when bugs crop up, because bug reports are like a personal insult to them.
Maintainers that have that attitude just shouldn't have public bug trackers that anyone can submit to. If they choose to do so anyway, and react poorly to legitimate bugs that are respectfully presented, that's on the maintainer, not the reporter.
I've been yelled at for reporting what I saw as a bug (coz I thought the behavior was bizarre and unexpected) and the author saw as a support request (coz he saw it as expected).
Another common pattern is this "no man's land" of bug responsibility between projects. Project A interacts with project B and that interaction causes a bug or awful problem. Project A and B both wash their hands of it.
I don't particularly mind support requests via the bug tracker - particularly since a pattern of support requests often highlights a UX issue or a lack of clarity in the docs.
Some people view them as irritating annoyances that should be pushed to some forum like stack overflow though.
> Some people view them as irritating annoyances that should be pushed to some forum like stack overflow though.
I maintain a fairly large open source project. We close "issues" that are support requests on sight, with a more-or-less automatic message telling the person that they should use Stack Overflow or Gitter for questions.
This is not because they are irritating annoyances. I in fact do support people on Stack Overflow and Gitter about the project. But there are at least two reasons for keeping things separate:
a) In terms of organization, I need the issue list to be about things that are actionable in the repo.
b) More importantly: only the core developers and some very enthusiastic people follow the GitHub repo. There are many more people available for and willing to support on Stack Overflow and Gitter. It is important that support requests reach these people so that support can be distributed. A lot of users even have more practical experience with the project than the core developers.
Personally, I don't like Gitter or Slack as I find them much harder to search or find already answered questions. Stack Overflow works very well though, a question-answer format is perfect for support requests. Its also much easier to search or link to. I think that Github issues feel closer to that for many people.
Its also important that the project clearly specifies where to ask for help. I'm often reluctant to open issues that aren't bug reports, but the project isn't clear where I should ask.
I wonder if it would be beneficial if github added a support forum to each repo, though having to deal with spam may turn into a major overhead. It would give the opportunity to contribute to a project to those with less technical skills and all the information would be in one place. Gitlab and other products may already have this, I don't tend to use them.
GitHub has "Discussions" on the way[1] which seem like they will greatly help the situation. You can see one in action here[2], which is where I first saw it. Doesn't seem to be generally available yet though, but when it is, I think it will improve issues greatly.
The worst is when project B is a closed source project. I have such an open-source project A that interacts with such a project B. That is the worst. Then I get a bug report, project B got a new version and your project A does not work anymore. Fix it! Then I ask what was changed in the new version of project B. Then they say, they do not know. Then I ask the company of project B. They do not respond. Then I get another email from a user, you need to fix it for the new project B version. Then I send 5 emails to the company of project B. Then they respond, "we do not support project A". And I do not have access to project B myself
Not me. I appreciate bug reports and the time the submitter took to post them. Even if they aren't clear enough for me to find the problem, someone else may run over the bug, too, and having multiple inadequate submissions often provides enough clues that we can fix the problem.
No need to stroke our egos, just the facts is just fine.
If that's actually what you wrote, I would be annoyed as a maintainer. There's an implied assumption here that "command X" was never tested and must therefore crash for everyone. In 99% of cases, "command X" runs without issue and has been tested on multiple configurations. If it turns out that "command X" crashes for you because your company's IT department misconfigured the certificate authorities on a particular Windows build image, you end up wasting massive amounts of everyone's time. After maintainers get burned by these kind of bug reports tens of times, they understandably get hostile to such low effort bug reporting.
If that's how you react, then you're a part of the problem. If someone opens a bug report that factually represents behavior they've seen, and provides supporting evidence and information, and you react that way, you should probably re-examine your world view and think hard about why you believe that everyone is out to unfairly criticize your work.
> If it turns out that "command X" crashes for you...
As a project maintainer, I hope you recognize that people will run your software on all sorts of hardware and software configurations that don't match how you've tested it. It's impossible for you to test all possible scenarios. Requiring that every potential bug reporter explicitly acknowledge that their issue might be unique to their particular setup in order to assuage your apparently-fragile ego is unreasonable and counter-productive.
Sure, as long as you're polite about it (and it would be incumbent on the reporter to be polite as well). It's not your responsibility to help users debug. If you do that often, for issues that are actually more widely reproducible, your software might end up getting a reputation for instability. Whether you care about that or not is up to you.
That is up to you. Different people/projects have different standards for how much effort they put into a bug.
If you think the issue is unlikely to be an actual bug, that would seem like the correct course to take. If you suspect it might depend on other details and you're keen to investigate more, you could ask for more details.
One related thing that many projects do is to have a bug template that asks for details such as software versions, operating system, CPU, etc. This can help a lot in reproducing bugs.
> So if I run the same command with all of the parameters you specify and it works correctly, I can close your issue as non-reproducible, right?
Depends how you want your project to be perceived.
If you don't give a crap, and just want to close issues then sure. ;)
If you're interested in finding out why the bug is occurring in such a strange way, and potentially solving the problem... then working with the user to figure out the cause (whether it's their fault or not) is going to be more useful. :)
If you're the only maintainer of your project though, and it happens a lot then personally I'm not sure what the right approach is.
The projects I'm involved with do have it happen, but it's not that often. So we're not too burned out by those things.
If I post a bug report like "when I run command X, there's a crash", how many OSS authors get annoyed?
If anyone gets annoyed at that, this is a sign they need to take a break from the project (or from the bug database), not a sign that the bug reporter needs to do anything differently.