Skip to content

ralucaStan/etiquette

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 

Repository files navigation

GitHub Etiquette

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.

About

GitHub Etiquette

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published