How to Create a Code of Conduct for an Open-Source Project

Related chapterThe Files That Turn a Repository Into a ProjectRunning a Community Without It Running You

Creating a code of conduct is a first step toward a safe and welcoming community for an open-source project. Often, you write it before the community even exists. That way, the project starts with clear expectations and guidelines for behavior. The process has several steps: defining goals and scope, researching existing codes of conduct, drafting the document, reviewing and approving it, publishing and communicating it, and regularly reviewing and updating it.

Why do we need one?#

By adopting a code of conduct for your open-source project, you set clear expectations for participant behavior, which helps build a positive social atmosphere in your community. It protects your participants, and it protects you as the project maintainer: unproductive attitudes can ultimately leave you drained or unhappy about your work.

If you enforce a code of conduct, healthy and constructive behavior becomes the norm. Issues become less likely, and your project becomes a more welcoming and supportive environment for all.

Define the Goals and Scope#

The first step is to define the goals and scope of the project. Consider the project’s purpose, its intended audience, and the types of behavior you expect from contributors and users. The goals of the code of conduct should be clear and concise, and outline the expectations for all contributors, users, maintainers, and community members.

A code of conduct should also specify where it applies, who it applies to (including sponsors), what actions will be taken if someone violates it, and how individuals can report any violations. When we think about “where it applies”, we often think only of issues, pull requests, and discussions, but it can apply also to community events, social media, communication applications, etc.

Research Existing Codes of Conduct#

Whether the community already exists or not, the next step is to research existing codes of conduct to identify what works and what doesn’t, but also to have a base to work on. Review codes of conduct from similar projects or industries, and pick the best practices and guidelines to incorporate.

Contributor Covenant#

The Contributor Covenant is a widely-used code of conduct for free and open-source software projects, created by Coraline Ada Ehmke in 2014. It outlines specific behaviors expected from contributors, such as being respectful of differing viewpoints, avoiding offensive language, and refraining from harassment or discrimination. Its goal is to let everyone participate in open-source projects without fear of being marginalized or excluded, and to promote a culture of kindness and empathy in the tech industry.

Thousands of open-source projects and many prominent companies have adopted it, including Google, Intel, GitLab, and open-source projects including Vue.js, Symfony, Bootstrap. In 2021, it was included in the Organization for Ethical Source. The Contributor Covenant has played a significant role in promoting a culture of kindness and empathy within the open source community.

Adopting the Contributor Covenant as your code of conduct offers several benefits:

• It’s widely recognized within the community, so the values of the community can be instantly communicated and understood.
• Many have reviewed and adopted it, which makes it a trusted and reliable option.
• If you’re unsure how to create your own code of conduct, the Contributor Covenant is readily available. It’s a practical starting point for conduct that reflects the values of your community.
• It has been translated into multiple languages, making it accessible and inclusive for a diverse range of contributors.

Other Existing Codes of Conduct#

There are several other well-known codes of conduct in open source, in addition to the Contributor Covenant, or based on it:

• The Ubuntu Code of Conduct;
• The Mozilla Community Participation Guidelines with a very interesting explanation:

  “These guidelines have been adapted with modifications from Mozilla’s original Community Participation Guidelines, the Ubuntu Code of Conduct, Mozilla’s View Source Conference Code of Conduct, and the Rust Language Code of Conduct, which are based on Stumptown Syndicate’s Citizen Code of Conduct. Additional text from the LGBTQ in Technology Code of Conduct and the WisCon code of conduct. This document and all associated processes are only possible with the hard work of many, many Mozillians.”

• The Django Code of Conduct;
• The Rust Code of Conduct adapted from the Node.js Policy on Trolling as well as the Contributor Covenant v1.3.0;
• The CNCF Code of Conduct adapted from the Contributor Covenant v2.0;

These are just a few examples. Each code of conduct has its own focus and guidelines, but they all share the goal of promoting a respectful and inclusive environment for collaboration and contribution.

Draft the Code of Conduct#

After gathering research and input, draft the code of conduct. Write it in clear and concise language that all members of the community can easily understand.

It should include guidelines on behavior, as well as consequences for violating the code of conduct.

Specify the actions that will be taken if there is a violation of the code of conduct. Doing so conveys the seriousness with which you take the code of conduct, assures the community that complaints will be fairly and transparently reviewed, and demonstrates your commitment to enforcing it.

Provide a private way for people to report violations, and specify who will receive those reports. Offer an alternative option too, for people who need to report someone who receives those reports.

Review and Approval#

Once the code of conduct is drafted, review it with key stakeholders, including legal advisors in some cases, and any other relevant parties. They can give feedback and make sure it’s legally sound.

Publication and Communication#

Once the code of conduct is finalized, it should be published and communicated to the community.

This can be done through the:

• project’s website or documentation
  • with a link in the footer or elsewhere to a code of conduct stored anywhere.
  • by creating a dedicated page like in GitLab Code of Conduct.
• other communication channels like Slack, Discord, Mattermost, etc..
  • In Astro Lounge Discord, they have it for example in their “rules” channel which contains a link to their code of conduct stored on GitHub.
• source code repositories.
  • For open-source projects, this is mainly where you’re going to find it at the root level of the main repository of the organization.

Make sure all members of the community are aware of the code of conduct and understand its expectations. Also make it accessible to anyone, so you can link it when someone needs a reminder of the rules.

How to add it to source code repositories#

GitHub Provides Some Templates#

GitHub offers guidance on creating a Code of Conduct through templates available on their website. When adding a new CODE_OF_CONDUCT or CODE_OF_CONDUCT.md file through the interface at the root level of your repository, you can select from two different templates to add to your project:

• Contributor Covenant;
• Citizen Code Of Conduct;

You can then complete your code of conduct by filling out a form with the required information.

After reviewing your changes, submit them and GitHub creates a CODE_OF_CONDUCT.md file at the root level of your repository, and your repository now has a special display. You can see an example of this rendering in the GitHub Community repository.

Some details of this article may become obsolete, so check the latest version of the GitHub documentation for Adding a code of conduct to your project.

Manually#

Adding a code of conduct in your repository is straightforward and works on all source code repository services, including GitHub, GitLab, BitBucket, and more. Create a CODE_OF_CONDUCT or CODE_OF_CONDUCT.md file at the root level of your repository, depending on whether you prefer the Markdown or simple text format.

While GitHub provides guidance with templates, you can use any code of conduct you prefer. Most repository services other than GitHub don’t offer a dedicated display for code of conduct files. Open-source projects should still include one, as it’s considered a best practice. Stored at the root level of the project, it’s easy to reference as a standard for appropriate behavior within the community.

If you selected the Contributor Covenant as your code of conduct, there’s a neat trick to add a badge to your README.md file. You can do this by adding the following code:

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)

Reusable Code of Conduct in GitHub#

GitHub lets you reuse a code of conduct across multiple repositories by creating a default one. It’s part of the default community health files, including CONTRIBUTING, FUNDING, and issue and pull request templates. Any repository owned by the account that doesn’t have its own code of conduct file uses this default one. To set it up, create a .github public repository and add a CODE_OF_CONDUCT or CODE_OF_CONDUCT.md file at the root level of the repository.

For an example, see our .github public GitHub repository.

Some details of this article may become obsolete, so check the latest version of the GitHub documentation for Creating a default community health file.

Regular Review and Updates#

Review and update the code of conduct regularly to keep it relevant and effective. The whole community should take part, at regular intervals such as annually.

A useful tip for those using the Contributor Covenant is to subscribe to release notifications in project’s GitHub repository. This way, you’re alerted when a new version of the code of conduct is released, and your project stays up-to-date.

Enforcing the Code of Conduct#

It’s rare, but in any community, a member may violate the code of conduct. When this happens, moderators or maintainers can take several steps.

The first step is to gather information about the situation. Treat each community member’s voice as important as your own, and take any reports seriously. Investigate the matter even if it doesn’t match your own experience with that person. Before responding, take time to understand what happened by reading through the person’s past comments and conversations to better understand who they are and why they might have acted in such a way. Try to gather perspectives other than your own about this person and their behavior.

Once you have enough information, take appropriate action. Your goal as a moderator or maintainer is to build a safe, respectful, and collaborative environment. Think about how your response will affect the rest of your community’s behavior and expectations, as well as the situation itself.

Depending on the severity of the violation, you may give the person a public warning, or reach out privately. Either way, explain how their behavior negatively impacted others. In some cases, stronger action may be necessary, such as suspending or permanently banning the person from the project.