A CONTRIBUTING guide turns interest into useful participation by explaining how the project accepts issues, discussions, and changes.
A CONTRIBUTING guide tells people how to help a project without wasting maintainer time. It should explain what kinds of contributions are welcome, how to report issues, how to propose changes, how review works, and what checks a contributor should run before submitting.
The guide does not need to be formal or long. It needs to remove guesswork. A newcomer should understand whether to open an issue first, how to prepare a pull request, what style or tests matter, and how maintainers decide what to accept.
Start with what is welcome
Begin by naming the kinds of contributions the project wants. Code patches are only one category. Many projects also need bug reports, reproduction cases, documentation fixes, translations, examples, design feedback, accessibility reports, performance testing, packaging help, or triage.
Be equally clear about work that is not currently in scope. If the project is not accepting major features, platform ports, rewrites, support questions, or speculative plugin ideas, say so politely. Boundaries help contributors choose useful work and help maintainers avoid repeated explanations.
This section should reflect real maintainer capacity. Do not invite extensive help if nobody can review it.
Explain issue reports
Useful issue reports have enough detail for maintainers to reproduce or understand the problem. A contribution guide can reduce back-and-forth by saying what information belongs in a bug report.
Common fields include:
- project version;
- operating system or runtime version;
- steps to reproduce;
- expected result;
- actual result;
- error messages or logs;
- sample files or screenshots when safe to share;
- whether the problem happens on the latest release.
For security issues, give a separate reporting path if public issues are not appropriate. Do not ask users to publish sensitive credentials, private data, or exploit details in a public tracker.
Describe the change workflow
Explain how a change moves from idea to merge. Some projects want an issue opened before large work begins. Some accept small pull requests directly. Some use mailing lists, design discussions, or maintainer proposals.
Tell contributors how to branch, where to submit changes, how to title a pull request, and what information reviewers need. If the project uses templates, labels, signed commits, contributor certificates, or automated checks, mention them in practical terms.
Keep the workflow honest. If reviews are slow, say that maintainers are volunteers or that response times vary. Clear expectations prevent contributors from assuming silence means rejection or approval.
Give setup and test instructions
Contributors need a way to run the project and verify changes. Link to the README or developer docs if setup is already covered, but include the contribution-specific checks in the guide.
Useful details include dependency installation, local build commands, test commands, formatting rules, linting, documentation preview steps, and how to run a smaller test subset. If some checks require services, secrets, hardware, or large downloads, identify alternatives where possible.
Do not list commands that maintainers have not kept current. A short working command list is more useful than a complete but stale development manual.
State review expectations
Review expectations make the process fairer. Contributors should know whether maintainers review for correctness, tests, documentation, compatibility, performance, security, design direction, or long-term maintenance burden.
Explain whether maintainers may close duplicate issues, decline out-of-scope features, request smaller patches, or ask for documentation changes. This is especially important when a technically correct patch does not fit the project direction.
If the project has a code of conduct, link it from the contribution guide. Conduct rules and technical review rules answer different questions, but both shape the contributor experience.
Handle licensing and rights carefully
Contribution terms can matter. Some projects accept contributions under the same license as the project. Others use a developer certificate, contributor license agreement, or sign-off process. Do not copy legal language from another project unless it actually fits.
At minimum, the guide should tell contributors where to find the project license and whether contributions are expected to be provided under that license. If the project needs formal contributor terms, use primary documents and qualified advice.
Avoid hiding licensing expectations until after someone has written a large patch. A contributor should understand the basics before starting work.
A practical CONTRIBUTING guide outline
Adapt the structure to the project:
| Section | What it should answer |
|---|---|
| Welcome and scope | What help is useful, and what is out of scope? |
| Code of conduct | What behavior standards apply? |
| Issues | How should bugs, requests, and questions be reported? |
| Security reports | Where should sensitive issues go? |
| Development setup | How do contributors run the project locally? |
| Tests and style | Which checks should pass before review? |
| Pull requests | How should changes be submitted and described? |
| Review process | What do maintainers look for, and how long might it take? |
| Licensing | What terms apply to contributions? |
Small projects can combine several of these into shorter sections. Larger projects may need separate files for security, governance, code of conduct, and developer setup.
Keep it maintained
A CONTRIBUTING guide becomes harmful when it describes a process maintainers no longer follow. Review it when the build changes, tests move, maintainer capacity changes, or contribution rules become stricter.
Watch for repeated confusion in issues and pull requests. If contributors keep missing the same step, improve the guide rather than answering the same question manually.
The best contribution guide feels like a practical map. It tells people where to start, how to avoid common mistakes, and what maintainers need in order to review useful work.