Open Source Etiquette: Talking to Strangers Who Owe You Nothing

Everyone in open source is a volunteer until proven otherwise, including the maintainer you’re about to mention. That changes how you ask, how you wait and how you disagree. None of it is complicated, and most people learn it the hard way, in public.

Each rule below comes with a message not to send and a better one. The messages are ours; the situations are the ones maintainers see every week.

Search first, and say where you looked#

A maintainer’s first reflex with a new question is to search for it. Saying where you looked saves them that step, and shows you tried.

One question or one bug per issue: a thread about three problems gets closed when the first one is fixed. For bugs, How to Write a Bug Report That Gets Fixed covers what to put in.

React with 👍, don’t comment “+1”#

Every comment on an issue sends a notification, often an email, to everyone subscribed to it. On a popular issue, “+1” reaches hundreds of people and tells them nothing new. In January 2016, maintainers of projects across GitHub signed an open letter, Dear GitHub, that asked for exactly this: content-less “+1” comments “serve only to spam the maintainers and any others subscribed to the issue”. GitHub shipped reactions two months later.

A reaction notifies nobody and still counts: maintainers sort issues by it with sort:reactions-+1-desc in the search bar. To follow the issue, click Subscribe in its sidebar. That’s what most “+1” comments are really for.

Wait two weeks, then ask what’s missing#

Most maintainers work on evenings and weekends, in a time zone that isn’t yours. A week of silence on an issue or a pull request is normal. “Any update?” after three days notifies everyone again and asks a question with no useful answer.

The second one is real: Kelketek posted it on a Bootstrap pull request after 80 days, and it was merged within a week. Your First Contribution tells the full story: wait two weeks, ask once, ask what’s missing rather than when.

Say how before you spend a weekend on it#

A pull request nobody asked for can be the wrong approach, or a feature the project doesn’t want. A short comment first costs you five minutes and can save you two days.

“Can I work on this?” asks for permission; the second one asks for a decision a maintainer can make in one reply. Some projects never assign issues and just want the pull request: CONTRIBUTING.md says which. Can I Take This Issue? explains both sides.

Disagree with the code, not the person#

Review comments are short because reviewers are busy, not because they’re angry. Read them as questions about the code, and answer the same way: with the reason, and with room for the maintainer to decide.

• If a maintainer says no after your reason, the project is theirs. Say you disagree once, then accept it, or fork: that’s what the license is for.
• “You” in a review is about the code (“you’re calling this twice”), and reads as an attack when it isn’t. “This is called twice” says the same.

Write for someone reading in their second language#

The person reading your message may live anywhere, read it on a phone at night, and read English as a second or third language. Idioms and sarcasm don’t translate, and in text, sarcasm reads as contempt.

• Short sentences, one idea each. Code, versions and error messages as text, in code blocks.
• Translation tools are fine, and nobody minds. Write in your language and translate it; say so if you want.
• No row of exclamation marks and no capitals for urgency. Nothing in a public issue tracker is urgent to anyone but you.

Say thanks in the thread#

A fix that works for you rarely gets a comment: people upgrade and move on. A thank-you in the issue costs a line, and it’s often the only feedback a maintainer gets that something they did helped.

It goes both ways. When CyrilKrylatov worked out that a report on twbs/bootstrap#42242 wasn’t Bootstrap’s bug, Julien closed the issue with thanks to the reporter and to Cyril, by name. Thanking the people who help triage, answer or review is how a project keeps them.

When someone crosses the line, the code of conduct is for you too#

Most projects have a CODE_OF_CONDUCT.md, and it protects contributors as much as maintainers. If someone insults you, harasses you or keeps pushing after a no:

• Don’t answer in kind. One calm sentence, or nothing. The thread is public, and the next reader will judge both of you.
• Report it to the project: the code of conduct names a contact, often an email address. Include links to the comments.
• Report it to GitHub when it’s abuse or spam: the ⋯ menu on a comment has Report content (GitHub’s docs). You can also block the user from your account.

Maintainers have tools of their own: they can hide a comment as off-topic or abusive, or lock a conversation that has gone too far. When one of your comments is hidden, read the reason, and don’t post it again.

Do this now#

• Open the CONTRIBUTING.md of a project you use, and find how it wants questions and ideas: issues, Discussions or a chat.
• Find its CODE_OF_CONDUCT.md, and the contact it gives for reports.
• Next time you’re about to comment “+1”, react with 👍 and click Subscribe instead.
• Before you post your next comment, read it once as the maintainer, on a Sunday evening.
• Say thanks on one issue that got fixed for you.

Go further#

• Dear GitHub: the 2016 letter from maintainers, and GitHub’s answer below it. Most of what it asked for exists today.
• Can I Take This Issue?: the most common question on issue trackers, from both sides.
• How to Write a Bug Report That Gets Fixed: the same courtesy, applied to a bug report.
• Non-Code Contributions Maintainers Actually Want: once you know how to talk to a project, ways to help it.