131 lines
5.7 KiB
Markdown
131 lines
5.7 KiB
Markdown
# GitHub Etiquette
|
|
borrowed from [Open source etiquette](https://github.com/kossnocorp/opensource.how)
|
|
|
|
## Don't be mean!
|
|
|
|
Be nice!
|
|
|
|
## Don't be bossy!
|
|
|
|
It takes just a few seconds to type "Any updates on this?" but it takes much
|
|
more time and energy to write a report back to you. First of all, you're not
|
|
maintainers' boss, and they owe you nothing, not to mention a report.
|
|
|
|
These minutes could have been spent on something meaningful, so you not only
|
|
steal time from the maintainer, but also the whole community.
|
|
|
|
Don't write like a boss: "Why this isn't merged?" "What's the ETA?" "It blocks
|
|
us!" "What are the blockers?".
|
|
|
|
## Don't demand!
|
|
|
|
Never demand anything from maintainers. Always keep in mind that maintainers'
|
|
work is an act of goodwill — even labor backed by the community rarely pays
|
|
more than minimum wage, so communicate accordingly.
|
|
|
|
If you need a piece of information or help, say it politely. If you want to
|
|
have something done, never push.
|
|
|
|
First of all, you could have different priorities. You and your colleagues
|
|
might be aligned on the same goal, but maintainers can have a different focus.
|
|
Secondly, you might have a different perspective on the problem. Be ready to
|
|
accept a rejection of your proposal, feature, or bug report. Yes, sometimes,
|
|
bugs are features!
|
|
|
|
## Don't be noisy!
|
|
|
|
Comments like "I also have this error" and "+1" are never helpful. It's
|
|
especially tempting to type such comment when it's a critical issue, but that
|
|
adds additional pressure and distraction.
|
|
|
|
If you want the get the attention of the maintainer, at least contribute
|
|
something. If the issue lacks stack trace or reproductions steps, add it.
|
|
Don't feel capable of opening a PR? Create a minimal repo with the demo of the
|
|
error.
|
|
|
|
## Don't rush!
|
|
|
|
Take your time before reporting a bug or asking a question. First, make sure
|
|
you're not missing anything. Read the docs, Google the problem, search the
|
|
issues, double-check, and only then reach for help.
|
|
|
|
When you do reach for help, make sure that you provide as much information as
|
|
possible. Proactively present library versions, code example, reproduction
|
|
steps, etc. Describe the problem in detail. Don't wait for the maintainers to
|
|
ask you for that. Provide or at least offer to provide a minimal reproducible
|
|
example. This way, you'll minimize the effort that they have to put to help
|
|
you, which would maximize your chances to prompt response.
|
|
|
|
It's easy for you to assume that all they need is a short description of the
|
|
problem as the maintainers know their thing the best and provide additional
|
|
information only when they ask you. But in that's just a time steal and the
|
|
best way to get rightfully ignored.
|
|
|
|
## Don't be emotional!
|
|
|
|
When the deadline is approaching and you still have a lot to do, a bug or
|
|
unexpected behavior in the code you don't control is annoyance at least. Never
|
|
show it!
|
|
|
|
The maintainer has a different perspective and might not be aware of the
|
|
problem even if you feel like everything is broken. If you want to get help,
|
|
then be calm, objective, and patient.
|
|
|
|
## Don't patronize!
|
|
|
|
Never assume that the maintainer is less experienced or knowledgeable or
|
|
straight stupid. That better approach, tool, or decision that you have in mind
|
|
might have been considered or even planned. They have full context and had
|
|
much more time than you to think everything through, so more likely, it's you
|
|
who's confused.
|
|
|
|
It's reasonable to think that the maintainer is an expert in the subject, and
|
|
you're not. Even if you find an objectively low-quality code, don't assume the
|
|
authors' experience or skills.
|
|
|
|
If you disagree with the direction, instead of arguing, it's better to
|
|
consider an alternative. Some prefer functional programming, some
|
|
object-oriented code, but that doesn't mean that latter or former are wrong.
|
|
The maintainer should be able to decide what trade-off to choose regardless of
|
|
your needs or views.
|
|
|
|
## Don't forget to say thanks!
|
|
|
|
Simple words of gratitude and praises are often the sole motivator that makes
|
|
open-source authors keep going, so don't be shy and say it!
|
|
|
|
Do you want to see a pull-request merged, much-needed feature implemented and
|
|
long-awaiter release shipped? Instead of reminding how much work is on their
|
|
plate by asking "any news" or showing dissatisfaction (which only kills the
|
|
motivation), say how their work is essential. Tell how much you value them.
|
|
Tweet kind words about them and their project. Sometimes that's the best you
|
|
can do.
|
|
|
|
## Don't cause drama!
|
|
|
|
Never post comments that might cause a drama or emotionally hurt maintainers.
|
|
|
|
You might be upset about maintainers intrusively asking for donations. You
|
|
might be frustrated by the lack of attention to your issue. You might be
|
|
dissatisfied with the quality of the project. You might know the better
|
|
alternative. You might think that's enough for you to post a comment demanding
|
|
to remove annoying ads or announce that you're moving to another solution. No,
|
|
it's not.
|
|
|
|
For you, that would be a simple message, but on another end, it might ruin the
|
|
day or strip out the motivation to continue. That's not the right way to treat
|
|
people that decided to give something for you for free, even if it's not good
|
|
enough.
|
|
|
|
## Don't surprise!
|
|
|
|
If you plan to contribute great work to a project, communicate it first. Your
|
|
vision might differ from the maintainers' one, or it could collide with their
|
|
plans or ongoing work. The worst way you could help them is to create more
|
|
work.
|
|
|
|
If you get rejected, be understanding and not try to cause the feeling of
|
|
guilt. It's already hard for maintainers to say no, so don't make it harder.
|
|
Feel free to clarify your intention if you think they misunderstood you but
|
|
never start an argument.
|