How to Write an Effective Code of Conduct for GitHub Repositories

A GitHub repository does not become a healthy community just because the code is useful. The moment other people begin opening issues, commenting on pull requests, or submitting patches, you have a social space to maintain as well as a technical one. A code of conduct is the document that defines what kind of community you are trying to build, what behavior is expected, and what happens when those expectations are ignored.

The best code of conduct files are not there for optics. They are there to reduce ambiguity. They tell contributors what respectful participation looks like, give maintainers a clear basis for moderation, and provide a reporting path when something goes wrong. Done well, they make a project safer, more predictable, and easier to contribute to.

What a Code of Conduct Is For¶

A code of conduct does three jobs at once:

• It sets expectations for how contributors, maintainers, and users should interact.
• It gives maintainers a documented basis for addressing harassment, abuse, and other harmful behavior.
• It tells affected people how to report a problem and what kind of response they can expect.

That last part matters more than many projects realize.

A list of values without an enforcement path is not very useful in practice. If someone experiences harassment and the document does not say who to contact or how reports are handled, the policy stops being a tool and becomes branding.

What Makes It Effective¶

An effective code of conduct is:

• Clear: It uses direct language instead of vague aspirational statements.
• Actionable: It describes both expected behavior and unacceptable behavior.
• Enforceable: It identifies a reporting path and explains how maintainers will respond.
• Scoped: It explains where the policy applies, such as issues, pull requests, discussions, chats, and events.
• Maintained: It reflects the actual project team and current contact information.

If the file reads like a generic statement that was copied into the repository and never reviewed again, contributors can usually tell. The goal is not to sound corporate. The goal is to be usable when tension is high and someone needs clear direction.

Start with a Proven Baseline¶

For most GitHub projects, the best starting point is not a blank file. It is an established framework such as the Contributor Covenant. At the time of writing, the current release is Contributor Covenant version 3.0. Starting from a well-known template gives you language that communities already recognize and that has been refined over time.

That does not mean you should paste it in unchanged and move on. A template becomes effective only after you adapt the enforcement contact details, scope, and moderation process to match your project.

Another valid model is the broader organization-level community guidelines approach used by some companies and large open-source ecosystems, such as HashiCorp's Community Guidelines. That kind of document usually operates at a higher level than a single repository and can work well when many projects share the same moderation philosophy.

For a typical GitHub repository, though, a focused CODE_OF_CONDUCT.md is still the most direct and contributor-friendly starting point.

Sections That Matter Most¶

Values and Expected Behavior¶

Begin with the kind of community you want to foster. This should be short and concrete. A few lines are enough to establish the tone: respectful communication, constructive feedback, professional disagreement, empathy, and inclusion.

Then list examples of behavior that support those values. For example:

• Showing empathy and patience toward other community members
• Giving and receiving feedback constructively
• Respecting differing viewpoints and experiences
• Assuming good intent while still addressing harmful impact

This section should help a reasonable contributor understand how to participate well, not read like a mission statement written by committee.

Unacceptable Behavior¶

Do not make contributors infer what crosses the line. Spell it out. A code of conduct should explicitly prohibit things like:

• Harassment, threats, or intimidation
• Personal attacks, insults, or discriminatory language
• Sexualized language or unwanted sexual attention
• Doxxing or sharing private information without permission
• Sustained disruption of discussions, reviews, or community spaces
• Trolling, baiting, or bad-faith engagement

This list does not need to be exhaustive, but it should be specific enough that moderators and contributors are operating from the same baseline.

Scope¶

Projects often forget to define where the code of conduct applies. Say so directly. Typical scope includes:

• Issues, pull requests, reviews, and discussions
• Project documentation repositories and associated websites
• Chat spaces such as Discord or Slack if they are official project spaces
• Community events, livestreams, and conference sessions representing the project

If the policy applies when someone is representing the project in public, include that too.

Scope matters because it prevents arguments later about whether a specific space is included.

Reporting¶

This section turns a statement into an operational document. Contributors should not have to guess how to report a problem.

A strong reporting section includes:

• A specific contact method, such as an email alias or contact form
• Guidance not to file public issues for conduct violations
• A request for relevant context, such as links or screenshots, if available
• A statement that reports will be handled as confidentially as possible

Use a contact method that someone actually monitors. A [email protected] contact alias that no one checks is worse than a direct maintainer address that is real and responsive.

Enforcement¶

Explain what maintainers may do in response to a violation. This does not need to be long, but it should be concrete. Typical enforcement actions include:

• Removing or editing comments
• Locking discussions
• Rejecting or closing contributions
• Temporarily muting or suspending community access
• Permanently banning a participant from project spaces

It also helps to say that maintainers will review reports, evaluate context, and choose a response proportionate to the behavior. That gives you flexibility while still making clear that violations have consequences.

Contributor Covenant 3.0 is a particularly strong baseline because it is recognizable, maintainer-friendly, and explicit about community standards and enforcement. Even if you do not adopt it verbatim, it is worth reading before you draft your own policy.

A Practical Example¶

Full Repository Example¶

Here is a simple example suitable for many projects:

# Code of Conduct

## Our Community

We are committed to creating a respectful, inclusive, and constructive environment for
everyone participating in this project. We want discussions to be productive, welcoming,
and centered on improving the project together.

## Expected Behavior

Examples of behavior that contribute to a positive environment include:

- Showing respect and empathy toward other people
- Giving constructive feedback and receiving it professionally
- Respecting differing viewpoints and experiences
- Focusing on the technical issue or idea rather than the person
- Helping make the project welcoming to new contributors

## Unacceptable Behavior

Examples of unacceptable behavior include:

- Harassment, threats, or intimidation
- Insults, personal attacks, or discriminatory language
- Sexualized language or unwanted sexual attention
- Publishing someone's private information without explicit permission
- Trolling, deliberate provocation, or sustained disruption of discussions
- Any other conduct that a maintainer reasonably determines is inappropriate in a
  professional community setting

## Scope

This Code of Conduct applies to all project spaces, including GitHub issues, pull requests,
reviews, discussions, documentation, and any other official communication channels for the
project. It also applies when an individual is representing the project in public spaces.

## Reporting

If you experience or witness unacceptable behavior, please report it privately to
[email protected]. Do not open a public GitHub issue for Code of Conduct reports.

Please include any relevant context, such as links, screenshots, or a description of what
happened. Reports will be reviewed promptly and handled as confidentially as possible.

## Enforcement

Project maintainers are responsible for clarifying and enforcing this Code of Conduct.
They may take any action they deem appropriate in response to behavior that violates this
policy, including warning a contributor, removing content, restricting interaction, or
permanently banning a participant from project spaces.

## Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 3.0:
https://www.contributor-covenant.org/version/3/0/code_of_conduct/

This example is intentionally plain. That is a strength, not a weakness. In a code of conduct, readability matters more than rhetorical flourish.

Organization-Level Pointer Example¶

If your repository inherits an organization-wide policy, a short pointer file can also work well:

# Code of Conduct

Our community guidelines apply to you when interacting with the community here on GitHub and contributing code.

Please read the full text at https://example.com/community-guidelines

This pattern is especially useful when the source of truth lives outside the repository and is maintained centrally for many projects. The key is to make the relationship explicit so contributors immediately know which policy governs the project. If your repository needs a different reporting path, extra project-specific expectations, or additional moderation detail, add that locally instead of relying on the pointer alone.

Where to Put It in a GitHub Repository¶

GitHub recognizes CODE_OF_CONDUCT.md as a community health file. In a repository, place it in one of the standard supported locations:

• CODE_OF_CONDUCT.md in the repository root
• .github/CODE_OF_CONDUCT.md
• docs/CODE_OF_CONDUCT.md

For most repositories, .github/CODE_OF_CONDUCT.md is the best home. It keeps project governance files together and out of the main working tree.

If you manage multiple repositories, you can also place a default CODE_OF_CONDUCT.md in a special .github repository for your account or organization. Repositories that do not define their own version can inherit that default, though the scope depends on who owns the .github repository: personal-account defaults apply to public repositories, while organization defaults can apply across the organization's repositories.

Common Mistakes to Avoid¶

Treating It as a Checkbox¶

Adding a code of conduct just to satisfy GitHub's community standards checklist misses the point. If the reporting address is stale, the maintainers are not aligned on enforcement, or the file has never been read by the people expected to apply it, the policy is decorative.

Being Too Vague¶

Statements like "be nice" or "be professional" are not enough. They leave too much room for people to rationalize harmful behavior and too little guidance for moderators deciding what to do.

Over-Lawyering the Text¶

A code of conduct is not a contract written for adversarial interpretation. Keep the language plain. People need to understand it quickly, especially under stress.

Omitting the Reporting Path¶

This is the most common failure mode. If there is no clear private reporting mechanism, the document does not help the person who needs it most.

Promising What You Cannot Deliver¶

Do not promise response times, confidentiality guarantees, or review structures that your team cannot realistically honor. It is better to say "handled as confidentially as possible" than to make an absolute promise you may not be able to keep.

Maintainer Alignment Matters More Than Perfect Wording¶

The text of the policy matters, but the maintainers' shared understanding matters more. Before publishing a code of conduct, make sure the people responsible for moderation agree on a few basic questions:

• Who receives reports?
• Who decides on enforcement actions?
• How will conflicts of interest be handled?
• When should outside help be involved?
• How will the team document incidents internally?

You do not need a massive governance process for a small project. You do need enough agreement that two maintainers do not respond to the same report in contradictory ways.

An effective code of conduct does not make conflict disappear. What it does is give your project a fairer, clearer, and more consistent way to respond when conflict appears.

If you maintain a project that welcomes outside participation, this file is part of the project's infrastructure just as much as CONTRIBUTING.md, issue templates, and CI workflows.

Write it with the same care. Keep it current. Make sure the contact path works. Then, if you ever need it, the policy will be more than a document. It will be a tool.