3fffc5c7d3
* Add contributing guidelines with AI-assisted contributions policy * Fix formatting * Rewrite contributing guide with welcoming tone Address review feedback: reframe guidelines to assume good faith and educate rather than warn. Adopt a "Change Ownership" principle inspired by wgpu's guidelines. Remove defensive "what will get your PR closed" section and hostile language. Same policies, better tone. Also fix README.md relative link style for consistency. * Add How to Contribute section before policies Move contributor guidance (open issues, Discord, Contributor Book) to the top of the document so new contributors see how to get started before reading policies. Simplify the Getting Help section to avoid duplication. * Update CONTRIBUTING.md * Reorganize PR section --------- Co-authored-by: Guillaume Lagrange <lagrange.guillaume.1@gmail.com>
4.6 KiB
Contributing to Burn
Welcome to the Burn community! We're glad you're interested in contributing.
How to Contribute
The best way to get started is to look at open issues
and find one that interests you. Issues labeled good first issue are a great starting point for
new contributors.
If you have an idea that isn't covered by an existing issue, open one first to discuss the approach. This helps align expectations and avoids wasted effort on both sides.
For questions, discussions, or just to say hello, join us on Discord. The Contributor Book covers architecture, environment setup, and guides for common tasks.
Pull Requests
Every pull request should have a descriptive title, a description covering what you changed, why, how you tested it, and a link to the relevant issue (if applicable). Prefer small, focused PRs over large ones that bundle unrelated changes.
Draft pull requests are considered not yet ready for review.
CI checks should pass before requesting review, though the signal isn't always accurate. If you have questions or need early feedback, let us know on the PR or on Discord.
Change Ownership
The core principle behind all contributions: PR authors must understand, justify, and explain every change they propose. After a PR is accepted, both the reviewer and the author should be confident it improves the codebase.
This applies equally whether you wrote the code from scratch, adapted it from another project, or used AI tools to help generate it. The origin of the code doesn't matter; what matters is that you own it intellectually and can stand behind it during review.
AI-Assisted Contributions
Using LLMs and AI tools to generate code that is part of a contribution is allowed.
That said, the Change Ownership principle applies fully. You are the author, not your AI tool. This means:
- Read and understand every line before submitting.
- Review AI-generated code for correctness, style consistency, and relevance.
- Test your changes locally and confirm they work as intended.
- Be prepared to explain the rationale behind any change during review.
Do not use "AI generated" as a justification for low-quality code.
Before You Open a PR
- Check for an existing issue. If there isn't one, open an issue first to discuss the approach. This is especially important for large changes or refactors.
- Read the codebase. Understand the architecture and conventions already in place. The Contributor Book covers architecture, environment setup, and guides for common tasks.
- Keep it focused. One PR should address one concern. If you spot an unrelated issue while working, open a separate PR for it.
- Run validation. Run
cargo run-checksbefore submitting. This runs formatting, linting, and the full test suite. All checks must pass.
Code Quality Standards
- Follow existing code style and project conventions.
- Write idiomatic Rust. If you are new to the codebase, study existing patterns before contributing.
- Keep dependencies minimal. Don't introduce new crates without discussion.
- Document public APIs. Non-trivial logic should have comments explaining why, not just what.
- Prefer clarity over cleverness.
- Bug fixes should include a regression test.
Large Pull Requests
Large, complex PRs are harder to review effectively and carry more risk. To help both yourself and reviewers, consider breaking substantial changes into smaller, incremental PRs. Each should be valuable on its own, even if the full picture spans multiple PRs.
Large efforts that are ultimately rejected are frustrating for everyone involved. If you're planning a substantial change, open an issue or start a discussion first. It's much easier to course-correct early than after the work is done.
Review Process
- Maintainers review PRs as time allows. Please be patient.
- Be responsive to feedback. If changes are requested, address them or explain your reasoning.
- Reviewers may ask clarifying questions about any part of your PR. This is a normal part of collaborative review and helps ensure shared understanding.
- Don't force-push to rewrite history during an active review without notice.
- If a PR goes stale for more than 14 days without a response from the author, it may be closed.
Getting Help
If you're stuck or unsure about something, don't hesitate to ask. Open an issue, start a discussion, or reach out on Discord. We're happy to help.