Open source etiquette

Before you start contributing to an open source project, ask yourself why you want to do that. It is fine if the answer to this question is just "I'm bored and I want to find something productive to do with my time", but you can probably go deeper than that.

Even better reasons might include:

• I use this tool all the time and found a bug in it/want to help make it better.
• I want to help other people use the tool more successfully.
• I want to help other people contribute to the project more successfully.
• I want to improve my own skills.
• I want to publicly demonstrate my own skills as part of my college or university course.
• I want to publicly demonstrate my own skills to improve my chances of getting a job.

Some of these reasons are self-serving, and that's OK — if you are spending your time working on a project for free, then it is fair to expect to get something out of it. In addition, having a clear set of reasons for contributing will make it easier to decide what to work on first.

Your presence on the project should be productive, and it shouldn't stop others from being so too.

We could abbreviate this to "be kind". This is our number one bit of advice for anyone starting open source contributions.

Be kind to the other contributors on the project, and it will be a happier and more productive place. This includes:

• Thanking people if they help you.
• Congratulating people where appropriate (for example if they land their first ever pull request, or fix a particularly difficult bug).
• Always responding respectfully to people, even if you feel like the answer to their question was a bit obvious, or that they are repeating themselves.
• Trying to help people to do better next time, in a supportive way, e.g. during pull request reviews or as you answer their questions. Saying "this is wrong" or "here is the answer" is nowhere near as helpful as saying "This is OK, but I feel that this would be better if you tried doing it more like this, here's a blog post for more ideas" or "you can find the answer here; also check out this link for more common answers".

You and the other contributors are (or should be) here because they want to make a positive contribution to the project, but beyond that, you can't assume anything about them. This includes their:

• Knowledge of the project and the technologies used to build it
• Gender, sexuality, age, languages spoken, location, political views, religion, or other personal attributes
• Experience with open source projects
• Confidence
• Expectations
• Sense of humor

You should therefore keep what you write on topic as much as possible, staying away from potential controversial off-topic subjects like religion or politics, and being supportive and respectful even if you disagree with someone, or don't like a decision they've made.

Also, you should refrain from any swearing / offensive language, even if it is not directed at anyone in particular. It is not needed for participation, and some people are really sensitive to it.

Be aware that there are rules in place in any good OSP to protect its contributors against being made to feel uncomfortable while contributing. This usually comes in the form of a CODE_OF_CONDUCT.md file on GitHub.

For example, MDN's repos are governed by the wide-reaching Mozilla Community Participation Guidelines. Usually mildly offensive behavior on MDN Web Docs repos (such as constantly being off-topic/disruptive, or being rude) will usually be first responded to by a warning on the repo, followed by a final warning, then a temporary or permanent ban. More serious behavioral problems such as hate speech or threats against another contributor will not be tolerated, and will likely result in an instant ban.

If you receive anything that makes you feel uncomfortable, you should always report it using the mechanism provided on the code of conduct.

Think about what you want to do on the project. For example, we have a large list of issues filed at on the contributors task board, broken up by various task types.

You could also contribute by opening pull requests to fix problems that you come across while reading MDN articles.

A lot of the work on MDN revolves around writing documentation and code examples, but there are other ways to contribute too:

• Help to triage issues that come in.
• Help fix typos.
• Help to improve grammar and make pages more understandable.
• Help to mentor people that are trying to make fixes.

Every fix is useful, no matter how small, and we won't turn any fix away. Nevertheless, try to make sure your fixes are productive. We'd like to advise against these kinds of contributions:

• Updating code styling just because "you like that style better".
• Updating language style "just because you like that style better".
• Changing pages from US English to British English.
• Adding or removing a bunch of punctuation when there's not really anything wrong.
• Changing the testing framework we are using for something else because you prefer it.

In many cases, things are like they are on OSPs for a reason. You should read their style guides if they have one, and if in doubt about whether something is productive, always ask first!

Good OSPs will always make contributor documentation readily available. On GitHub projects, it is usually in the repo's CONTRIBUTING.md file, or sometimes in the project's README.md file. Being a documentation project, MDN content has a README and a decent set of contributor docs on the site itself (see Contributing to MDN Web Docs).

Don't be afraid to ask for help, but ALWAYS try to find the answer to your question first before asking. This way you build up your knowledge of the project and become more independent, and don't put unnecessary burden on the other contributors.

Of course, the docs won't always be perfect. If an explanation is hard to find or not described very well, file an issue, or create a pull request to try to fix it yourself.

Always find out where the best place is to ask questions. Good OSPs will always make this clear in their docs (see Get in touch). If you want to ask general questions, then always make use of these channels. Don't just file an issue on GitHub for every question, as it adds noise to the project (see "Make progress, not noise" below).

Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn't make other contributor's jobs harder. Submitting pull requests to fix bugs is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise?

As a rule, do:

• Discuss one topic per issue — it is easy to keep issues focused and productive.
• Fix one issue per PR — it may be slightly more work for you, but it is much easier to review a single clear fix.
• Contribute to other threads if you have a useful point to make or can answer someone else's question.
• Ask questions using other mechanisms like chat rooms or forums if you are not sure whether something is useful or have a simple question.
• Read the manual first to try to answer the question yourself before asking it.

Don't:

• Complicate issues by trying to discuss multiple topics at once, or making off-topic comments.
• Try to cram multiple fixes into a single pull request. It makes it a lot harder to review, and raises suspicions (some people might think you are trying to hide some malicious code in between the valid changes).
• Open lots of issues asking vague questions.
• Ask questions without trying to solve the problem yourself first.

OSPs are quite democratic — many decisions are voted on, and you are largely free to contribute how you want, as long as you don't impede anyone else from contributing.

However, some things will be largely decided by a small group of core contributors. You are free to make a case against any decision, but sometimes a moderator will make a call that goes against your opinion. You need to respect and accept these decisions.

It is useful to get to know any project's moderators, so you know who best to ask for help, for example in pull requests or issue threads.

Bear in mind that many people working on OSPs are doing it in their free time, without payment, and all people working on OSPs are generally very busy. If you are waiting for something like a pull request review, or an answer to a question, be patient.

It is reasonable to wait a few days and then ping someone politely to ask if they've had time to look at it. If they happen to be too busy, it may be best to wait a further week and try following up with them then.

It is NOT reasonable to start demanding things, like a quick reply.

If someone is waiting for you to do something for them, you should be extended the same courtesy, but at the same time, try to respond as promptly as you can. If you really can't find the time, let them know, and ask the maintainers to help you find someone else to do the task.

• How to Contribute to Open Source
• More general freeCodeCamp "How to contribute to open source" list
• Getting started with contributing to open source