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."
I actually experience a lot of push back. Many project maintainers don't want more contributors, and feel like there are already too many cooks in the kitchen and they don't have time to help you figure out how to contribute or explain aspects of the existing code.
In general, the +1 sort of issues that I've seen mostly arise because (a) it's an implementation challenge that is not at all suited to a new contributor and needs significant attention from devs who are already very familiar; (b) it's a dev task that the existing devs don't want to do, for various reasons; and (c) it's a dev task that a huge and vocal contingent of users feels is really critical and that it's almost a dealbreaker in terms of their usage of the open source tool in the first place.
I feel like a lot of the replies on this thread that focus on pushing it back to the person who asked or the people who +1 are missing the point. The far more common scenario is when it's entirely implausible that any of those people could do it without intense and significant handholding from devs already familiar enough to do it more quickly themselves.
for claudia I have a policy of replying to issues with ideas on how to implement it, and closing the issue one week after if there was no activity. got a fair few happy contributors now, and more people know the code base so they respond to users on the chat channel even when I'm not around.
> 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.
By definition though, we're talking about issues that get a huge steam of +1's, and are unequivocally extremely useful to a wide group of the project's users.
When the project maintainers fail to prioritize the things that huge streams of users are +1-ing, I think that's a strong signal that the project maintainers just want to poke around their preferred aspects of the project, rather than address actual needs.
In that sense, they aren't actually "volunteering" time -- they are receiving the compensation of their satisfaction of poking around only the parts of the code they like. They aren't doing it "for" anyone but themselves, and it's this idea that all open source contributions are "volunteered" and are given infinity free passes from criticisms about prioritization that causes a lot of the trouble.
In order for the time to be "volunteered" it has to be directed at things that others are benefiting from. If few are benefiting and it's just a personal quirk, curiosity, or interest of some random developer -- who wants to tune out the +1 noise of people asking for things they actually need -- then that developer deserves zero praise or kudos for "volunteering" time or anything. There's no sense in which it's generous to fail to support aspects of a project that people need in order to instead support aspects of a project you personally happen to like.
I think a lot of the +1 streams are about this kind of tension. Developers saying, "leave me alone ... I'm already doing this 'for free' -- what more do you want." And then cranky users saying in reply, "But you're not doing anything 'for free' -- you're picking the parts that bring you personal satisfaction and then trying to argue that those are higher priority than the things project users rely on and need."
In some cases it may be reasonable, but generally it's not at all reasonable. As mentioned in another comment, there is no sense in which it's generous to forsake aspects of a project that people need or rely on in order to instead focus on aspects that you personally find interesting. That's no longer "volunteering" or "helping out" but in fact is actually just taking limited resources away from core project improvements, and is quite a selfish way to interact with a given open source community.
Of course, developers don't have to contribute to an open source project at all. And if they do, it doesn't have to be in a "volunteering" sense in which their work actively offers benefit to others. They are free to choose instead to more selfishly only prioritize contributing in ways they personally want or like. But if they do, then they no longer can turn around and act like others should be gracious for their "generous" contribution to the project.
I guess I would say that developers can ignore the useful stream of +1s in order to more selfishly work on aspects that bring them personal satisfaction, instead of deriving satisfaction from the benefit offered to wide ranges of users. It's not that it's reasonable or unreasonable. It's just literally a particular option they could choose.
If they choose that, in cases where no serious rationale is given to explain why there is some more beneficial project agenda in the short term, then such petty disregard for a massive pile of evidence about what your project users needs are is a pretty strong indication of a bad library/project, with alarming dysfunction.
So in this sense, the +1 stream is a really useful barometer of the project.
Either the core developers say, "whoops, my bad, I had been intending to volunteer time which necessarily implies that my efforts should be focused on whatever the users benefit from the most -- let me switch to work on this hugely +1'd issue I'd been ignoring" ... or they say, "I hear you everybody, but since I'm more familiar with the project internals, let me offer a technical rationale for why we need to delay addressing this in order to work on other stuff first" ... or they say, "Screw you all for bothering me. I'm 'volunteering' my time on this, so I'm going to do what I want. I don't like this big +1'd issue, so I'm going to ignore it and just do whatever."
Either way it gives you a ton of information about the health and reliability of the project.
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.