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.
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)
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.
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.
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.
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.
Understand that as the consumer of a FOSS project you are entitled only to terms specified in the license. Usually those do not include free customer support or a guarantee of quality. If you can't or don't want to contribute code you are certainly free to contribute money to help offset the cost of development for features you would like to see. But if you think it's appropriate to harass developers and usurp their development platform in an attempt to squeeze more thankless work out of them, there is something seriously wrong with your world view.
> 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.
That's very unrealistic. I may be a casual user of a tool, while the fix requires deep familiarity with internal parts. The age-old answer of "fix it yourself" is silly, unless project maintainers don't care if what they make actually helps people.
In your comment there again is this mention that the dev time is volunteered, but this is a red herring. The time isn't useful just because it's volunteered. It has to be both volunteered and directed at effort that addresses something people need. If it's volunteered, but not directed at something people need, I think it's perfectly reasonable that they use some mechanism to indicate they feel dev resources aren't being allocated in a satisfactory way.
I think it's reasonable to ask someone for a PR but it's also reasonable for that person to ask the maintainers how to do it. As a maintainer of a fairly popular library, I would love if everyone who "+1'd" a feature request asked on our slack channel how to implement it, or even emailed me. I've started closing feature requests that we aren't going to implement (don't belong in the core library) with something like "Closing because we will not implement this in the core. If you'd like to implement this as a plugin, post here and I can direct you in the right direction."
> The time isn't useful just because it's volunteered. It has to be both volunteered and directed at effort
useful depends on the target. something might be useful to you but not to other people. big part of successful product management is deciding on good market segments. as a casual user of a tool, you might not be in a segment that the project maintainers care a lot. annoying maintainers won't help at all if that is the case. learning about the code and fixing it will.
My specific problem (and the reason for the +1 above) was that I did submit a PR that would be very easy to merge and the maintainer has been sitting on it for months :(
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.
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
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.