5 ms·

GitHub Issues Do's and Don'ts

71 points by martyhu 10y ago

hrolff 10y ago
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
knocte 10y ago
This should not be targeted just to github issues users but to any bug reporting audience. (On a sidenote; I like gitlab issues so much more than github's now, they have emulated trello to add dnd kanbas style to them)
rpedela 10y ago
I think there is an exception to the don't +1 rule. I think saying +1 is fine as long as you follow up with an insightful comment. For example, explaining your specific use case for the feature because that information could help whoever implements it.
- trentmb 10y ago
  > For example, explaining your specific use case for the feature because that information could help whoever implements it. Then just post that.
  - koolba 10y ago
    > Then just post that. Having the +1 or -1 at the start of the comment helps a reader scan through quickly to find the pro/con comments. It's easier to track the conversation.
- StavrosK 10y ago
  I needed to +1 something (as in, saying "this affects me too" literally five minutes ago, and felt bad that wasn't more constructive, but it was the only way to send the maintainer a notification about the issue. If I had just thumbsupped it, nobody would have been notified and seen that it affects more than one person.
  - p4wnc6 10y ago
    Same here. When an issue goes unaddressed for a long time, yet the user base clearly needs it to be addressed, there has to be a mechanism by which the user base can make it annoying to the developers who continue to choose not to address it. Making it annoying for them, e.g. by a constant reminder that many people support some action to be taken, is the whole point. That way, projects can't simply define away critical changes that users have good reason for wanting. If it's easy for project maintainers to make a dictatorial or unilateral decision to ignore something a large body of users wants, and they can do that without paying any sort of annoyance penalty, it's super bad for the project. The mechanism of user needs no longer steers development priorities. I see this happen often on projects where someone wants publicity or credit for their work on something open source, and so prioritizes demo-ware aspects of the project, or showy new features, over critical long-term problems, refactoring workflows, or basic utilities that are sorely needed. Typically there are arguments of the sort, "I'm giving my development time for free, so leave me alone to work only on the aspects that I want" -- and these broadly form the basis of wanting to disallow +1-like pinging, annoying reminder behaviors. The trouble is no one cares what your motivations are for choosing to contribute to the project. No one who uses the open source project has any reason whatsoever to care that you found some cost/benefit tradeoff to be favorable, for personal reasons, and to motivate you to contribute. The project ecosystem generally just wants implementers who will prioritize things as-needed by large sections of the user base, and who will not complain if that means they don't get to use their "donated" time to work only on aspects they personally want. So it creates a natural tension. Getting rid of +1-like pedancy would be bad, IMO, because it puts all of the prioritization power into the hands of the people who are choosing what to do by their mere wants rather than project needs. I'd like there to be a mechanism that penalizes want-pursuit a little more.
    - adzicg 10y ago
      > Same here. When an issue goes unaddressed for a long time, yet the user base clearly needs it to be addressed, there has to be a mechanism by which the user base can make it annoying to the developers who continue to choose not to address it. instead of trying to annoy people who volunteered their own time to build something useful, why not submit a pull request instead? if it's that important to you, invest a bit more into solving the problem than just complaining online.
- JohnTHaller 10y ago
  If you want to +1, use the voting feature. If you have a comment that will add to determining the problem or arriving at the solution, type that. +1 in comments is just noise.
sixhobbits 10y ago
I know it's controversial, but I think Dos and Don'ts as is correct English grammar and faithful to the author's title is strongly preferable to Do's and Don'ts (Apostrophe is never used for pluralization, although I know that "Dos" looks really strange). The other option is to quote both words and to put the apostrophes outside the quotes "Do"s and "Don't"s
alangpierce 10y ago
I like this list, but I would also add "Don't worry so much about these rules.". At least for me, I've often wanted to contribute to an open source project or participate in a discussion, but I was scared to because I was worried that I would say something wrong or not follow some implicit norm. Probably, the whole "RTFM culture" (or at least my perception/worry of it) had a net negative effect in my case because I ended up not contributing in cases where I probably could have positively contributed. It really depends on your personality, though. If you're the type of person who naturally just speaks your mind without hesitation, then it's nice to slow down a bit and be more thoughtful, especially if you're dealing with a complex topic or your comment will be read by many people. But if you're more shy, you shouldn't feel the need to go through this checklist 5 times before submitting any comment or PR. Similarly, if you're maintaining an open source project and someone breaks one of these "rules", be polite and be thankful that they're trying to help out. Allowing people to make little mistakes and learn from those mistakes is much more welcoming and human than "you must read this giant list of docs before you're allowed to speak". There's a balance to everything, of course, but you'll get a stronger community and help people grow if you're more welcoming.

71 points by martyhu 10y ago

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

This should not be targeted just to github issues users but to any bug reporting audience. (On a sidenote; I like gitlab issues so much more than github's now, they have emulated trello to add dnd kanbas style to them)

rpedela 10y ago

I think there is an exception to the don't +1 rule. I think saying +1 is fine as long as you follow up with an insightful comment. For example, explaining your specific use case for the feature because that information could help whoever implements it.

trentmb 10y ago
> For example, explaining your specific use case for the feature because that information could help whoever implements it. Then just post that.
- koolba 10y ago
  > Then just post that. Having the +1 or -1 at the start of the comment helps a reader scan through quickly to find the pro/con comments. It's easier to track the conversation.
StavrosK 10y ago
I needed to +1 something (as in, saying "this affects me too" literally five minutes ago, and felt bad that wasn't more constructive, but it was the only way to send the maintainer a notification about the issue. If I had just thumbsupped it, nobody would have been notified and seen that it affects more than one person.
- p4wnc6 10y ago
  Same here. When an issue goes unaddressed for a long time, yet the user base clearly needs it to be addressed, there has to be a mechanism by which the user base can make it annoying to the developers who continue to choose not to address it. Making it annoying for them, e.g. by a constant reminder that many people support some action to be taken, is the whole point. That way, projects can't simply define away critical changes that users have good reason for wanting. If it's easy for project maintainers to make a dictatorial or unilateral decision to ignore something a large body of users wants, and they can do that without paying any sort of annoyance penalty, it's super bad for the project. The mechanism of user needs no longer steers development priorities. I see this happen often on projects where someone wants publicity or credit for their work on something open source, and so prioritizes demo-ware aspects of the project, or showy new features, over critical long-term problems, refactoring workflows, or basic utilities that are sorely needed. Typically there are arguments of the sort, "I'm giving my development time for free, so leave me alone to work only on the aspects that I want" -- and these broadly form the basis of wanting to disallow +1-like pinging, annoying reminder behaviors. The trouble is no one cares what your motivations are for choosing to contribute to the project. No one who uses the open source project has any reason whatsoever to care that you found some cost/benefit tradeoff to be favorable, for personal reasons, and to motivate you to contribute. The project ecosystem generally just wants implementers who will prioritize things as-needed by large sections of the user base, and who will not complain if that means they don't get to use their "donated" time to work only on aspects they personally want. So it creates a natural tension. Getting rid of +1-like pedancy would be bad, IMO, because it puts all of the prioritization power into the hands of the people who are choosing what to do by their mere wants rather than project needs. I'd like there to be a mechanism that penalizes want-pursuit a little more.
  - adzicg 10y ago
    > Same here. When an issue goes unaddressed for a long time, yet the user base clearly needs it to be addressed, there has to be a mechanism by which the user base can make it annoying to the developers who continue to choose not to address it. instead of trying to annoy people who volunteered their own time to build something useful, why not submit a pull request instead? if it's that important to you, invest a bit more into solving the problem than just complaining online.
JohnTHaller 10y ago
If you want to +1, use the voting feature. If you have a comment that will add to determining the problem or arriving at the solution, type that. +1 in comments is just noise.

sixhobbits 10y ago

I know it's controversial, but I think Dos and Don'ts as is correct English grammar and faithful to the author's title is strongly preferable to Do's and Don'ts (Apostrophe is never used for pluralization, although I know that "Dos" looks really strange). The other option is to quote both words and to put the apostrophes outside the quotes "Do"s and "Don't"s

alangpierce 10y ago

I like this list, but I would also add "Don't worry so much about these rules.". At least for me, I've often wanted to contribute to an open source project or participate in a discussion, but I was scared to because I was worried that I would say something wrong or not follow some implicit norm. Probably, the whole "RTFM culture" (or at least my perception/worry of it) had a net negative effect in my case because I ended up not contributing in cases where I probably could have positively contributed. It really depends on your personality, though. If you're the type of person who naturally just speaks your mind without hesitation, then it's nice to slow down a bit and be more thoughtful, especially if you're dealing with a complex topic or your comment will be read by many people. But if you're more shy, you shouldn't feel the need to go through this checklist 5 times before submitting any comment or PR. Similarly, if you're maintaining an open source project and someone breaks one of these "rules", be polite and be thankful that they're trying to help out. Allowing people to make little mistakes and learn from those mistakes is much more welcoming and human than "you must read this giant list of docs before you're allowed to speak". There's a balance to everything, of course, but you'll get a stronger community and help people grow if you're more welcoming.