Skip to content

6.6. Contributions

What is a Code of Conduct?

A Code of Conduct is a formal document that outlines the expected standards of behavior for all participants in your project's community. Its primary purpose is to foster a safe, welcoming, and inclusive environment where collaboration can thrive. By clearly defining norms and addressing issues like harassment, discrimination, and conflict resolution, you set a positive tone and encourage participation from a diverse range of contributors.

To add one to your project, you can follow the official GitHub guide or simply create a CODE_OF_CONDUCT.md file in your repository's root directory. For inspiration, see the examples on the Open Source Guides.

What are Contribution Guidelines?

Contribution guidelines are a set of instructions that explain how others can contribute to your project effectively. This document, typically named CONTRIBUTING.md, acts as a roadmap for potential contributors, detailing everything from coding standards and testing procedures to the pull request and review process. Clear guidelines streamline collaboration, reduce the burden on maintainers, and ensure that contributions align with the project's goals and quality standards.

You can learn how to set up these guidelines from the official GitHub documentation.

How Can You Build a Thriving Software Community?

Building a successful community is an active process that requires deliberate effort. Key strategies include:

  1. Foster Open Communication: Create channels for transparent and respectful dialogue, such as forums, chat platforms, or regular community calls. Ensure all members feel that their voices are heard and valued.
  2. Establish Clear Governance: Define roles (e.g., contributor, maintainer, admin), responsibilities, and decision-making processes. This clarity helps manage the community efficiently and empowers members to participate effectively.
  3. Recognize and Appreciate Contributions: Publicly acknowledge and celebrate all forms of contribution, from code and documentation to bug reports and community support. Recognition fosters a sense of value and encourages continued engagement.
  4. Promote Inclusivity and Mentorship: Actively work to create a welcoming space for people from all backgrounds. Implement mentorship programs where experienced members can guide newcomers, accelerating their growth and integration into the community.
  5. Provide Excellent Documentation: Invest in high-quality, accessible documentation. This lowers the barrier to entry, enabling more people to use and contribute to your project independently.

How Can You Empower Contributors?

Empowering contributors involves creating an environment where they can do their best work. This is achieved through mentorship, constructive feedback, and clear processes.

  1. Offer Constructive Code Reviews: Frame code reviews as a collaborative and educational process. Focus not only on technical correctness but also on best practices, design principles, and project conventions. Provide feedback that is specific, helpful, and kind.
  2. Create "Good First Issues": Curate a list of simple, well-defined tasks for newcomers. This helps them get acquainted with the codebase and contribution workflow, building their confidence for more complex contributions later.
  3. Provide Comprehensive Documentation: Ensure your project has clear, up-to-date documentation for both users and developers. This is the single most effective way to reduce friction and help contributors get started.
  4. Establish Mentorship Programs: Pair experienced contributors with new members. This direct guidance is invaluable for skill development and helps foster a stronger, more connected community.

Can the Code Review Process Be Automated?

Yes, automating parts of the code review process is a highly effective way to improve efficiency, consistency, and code quality. Automated tools can handle objective checks, freeing up human reviewers to focus on more nuanced aspects like design and logic.

For example, you can enable automated code reviews with Google Gemini Code Assist. After installing the Gemini Code Assist App from the GitHub Marketplace, you can add a .gemini/config.yaml file to your repository's root to configure its behavior:

# https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github
have_fun: false
code_review:
  disable: false
  comment_severity_threshold: MEDIUM
  max_review_comments: -1
  pull_request_opened:
    help: false
    summary: true
    code_review: true

With this configuration, Gemini Code Assist will automatically review new pull requests and provide feedback, helping to catch issues early in the development cycle.

How Can You Enforce Repository Standards on GitHub?

To ensure all contributions adhere to your project's standards, you can use GitHub rulesets. Rulesets allow you to define and enforce a collection of rules for specific branches, such as requiring a linear commit history, preventing force pushes, or mandating that all pull requests pass certain status checks before being merged.

Below is an example ruleset for a main branch, which can be saved as .github/rulesets/main.json:

{
  "name": "main",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "~DEFAULT_BRANCH"
      ]
    }
  },
  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "required_linear_history"
    },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": true,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false,
        "allowed_merge_methods": [
          "squash",
          "rebase"
        ]
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "do_not_enforce_on_create": false,
        "required_status_checks": [
          {
            "context": "checks",
            "integration_id": 15368
          }
        ]
      }
    },
    {
      "type": "non_fast_forward"
    }
  ],
  "bypass_actors": [
    {
      "actor_id": 5,
      "actor_type": "RepositoryRole",
      "bypass_mode": "always"
    }
  ]
}

You can apply this ruleset manually through the GitHub UI or automate it using a Just task:

# install github rulesets
[group('install')]
install-rulesets:
    #!/usr/bin/env bash
    set -euo pipefail
    repo=$(gh repo view --json=name --jq=.name)
    owner=$(gh repo view --json=owner --jq=.owner.login)
    gh api --method POST -H "Accept: application/vnd.github+json" \
    "/repos/$owner/$repo/rulesets" --input=".github/rulesets/main.json"

Additional Resources