Skip to main content
Moxie Docs

FREE TOOL

CONTRIBUTING.md Generator

A CONTRIBUTING.md template you can fill in, preview, and download.

Start from an open-source library, a Python project, or an internal monorepo, then replace the details with your own. No account needed.

Read how to write a CONTRIBUTING.md

Setup steps in CONTRIBUTING.md break quietly Export free above · connect a repo when you want Moxie Docs to keep it accurate

See how Moxie Docs keeps docs currentConnect GitHub free
Covers what contributors ask

Setup, tests, branch and commit rules, PR expectations, issue reporting, conduct, and license.

GitHub-ready

GitHub links CONTRIBUTING.md from new issues and pull requests when it sits in the repo root, docs/, or .github/.

Shareable drafts

The draft is encoded in the link, so maintainers can review it before it lands.

Runs in your browser

Nothing is uploaded. Copy the Markdown or download the file.

CONTRIBUTING.md examples

Example: Open-source library

Contributing to acme-sdk

Thanks for helping improve acme-sdk. Bug fixes, docs improvements, and new examples are always welcome. For larger features, open an issue first so we can agree on the approach before you write code.

Prerequisites#

  • Node.js 22 or later
  • pnpm 9
  • Git

Set up your environment#

Shell
git clone https://github.com/acme/acme-sdk.git
cd acme-sdk
pnpm install

Run tests and checks#

Shell
pnpm test
pnpm lint
pnpm typecheck

Branches and commits#

  • Branch from main using type/short-description, for example fix/retry-timeout.
  • Write commit messages in Conventional Commits format (feat:, fix:, docs:, chore:).
  • Keep each commit focused on one change.

Pull requests#

  • Link the issue your PR closes.
  • Add or update tests for any behavior change.
  • Add a changeset for anything that changes the public API.
  • One approving review from a maintainer is required to merge.
  • Maintainers aim to respond within three working days.

Code style#

  • Prettier formats on commit; run pnpm format if CI complains.
  • Avoid default exports.
  • Document public functions with TSDoc.

Reporting bugs and requesting features#

  • Search existing issues before opening a new one.
  • For bugs, include the SDK version, runtime, a minimal reproduction, and the full error.
  • Report security issues privately to security@acme.dev, not in public issues.

Code of conduct and license#

This project follows the Contributor Covenant code of conduct. By contributing, you agree your contributions are licensed under the MIT License.

Example: Python project

Contributing to dataflow

We welcome contributions of every size, from typo fixes to new connectors. If you are new to the project, issues labeled good-first-issue are a good place to start.

Prerequisites#

  • Python 3.12 or later
  • uv
  • Docker (for integration tests)

Set up your environment#

Shell
git clone https://github.com/acme/dataflow.git
cd dataflow
uv sync --all-extras

Run tests and checks#

Shell
uv run pytest
uv run ruff check .
uv run mypy src

Branches and commits#

  • Fork the repository and branch from main.
  • Use short, imperative commit messages.
  • Rebase on main before opening a PR rather than merging main into your branch.

Pull requests#

  • Fill in the PR template, including how you tested the change.
  • New connectors need integration tests and a docs page.
  • CI must pass before review.

Code style#

  • Ruff handles formatting and linting.
  • Type hints are required on all public functions.

Reporting bugs and requesting features#

  • Use the bug report template for bugs and the feature request template for ideas.
  • Include your Python version and operating system.

Code of conduct and license#

Please read CODE_OF_CONDUCT.md before participating. Contributions are licensed under Apache-2.0.

Example: Internal monorepo

Contributing to Platform monorepo

This guide is for engineers across teams contributing to the platform monorepo. Each package has an owning team listed in CODEOWNERS; they review changes to their area.

Prerequisites#

  • Node.js version from .nvmrc
  • bun
  • Access to the staging environment

Set up your environment#

Shell
bun install
cp apps/web/.env.example apps/web/.env.local
bun run dev

Run tests and checks#

Shell
bun run verify
bun run test:e2e

Branches and commits#

  • Branch from main as /-short-description.
  • Reference the ticket ID in the first commit message.
  • Never push directly to main.

Pull requests#

  • Keep PRs under roughly 400 changed lines where possible.
  • UI changes include a screenshot.
  • Database migrations ship to production before the code that reads them.
  • Update the docs in the same PR when behavior changes.

Code style#

  • Biome formats and lints on commit.
  • Use the shared UI components rather than one-off styles.

Reporting bugs and requesting features#

  • File bugs in the team's tracker with steps to reproduce and the affected environment.

Code of conduct and license#

Internal use only. Follow the engineering handbook's review etiquette.

CONTRIBUTING.md FAQ

What is a CONTRIBUTING.md file?

CONTRIBUTING.md is a Markdown file that tells people how to contribute to a repository: how to set up the project, run tests, format commits, open pull requests, and report bugs. GitHub surfaces it to anyone opening an issue or pull request.

Where should CONTRIBUTING.md go?

Put it in the repository root, the docs/ folder, or the .github/ folder. GitHub recognizes all three. A file in an organization's .github repository acts as the default for repositories that don't have their own.

What should a CONTRIBUTING.md include?

A short welcome and scope, prerequisites, local setup commands, how to run tests and linters, branch and commit conventions, what a good pull request contains and how review works, how to report bugs and security issues, and links to the code of conduct and license.

Do internal repositories need a CONTRIBUTING.md?

Yes. In a shared monorepo it answers the same questions for engineers from other teams, and coding agents such as Claude Code and Codex read it alongside AGENTS.md to learn how changes are expected to be made.

Keep it true

Setup steps in CONTRIBUTING.md break quietly

Export your CONTRIBUTING.md here. Connect GitHub when you want Moxie Docs to catch commands and conventions that drift from the code, and propose the fix as a pull request.

See how Moxie Docs keeps docs currentConnect GitHub free

Export free above · connect a repo when you want Moxie Docs to keep it accurate