Development workflow

The end-to-end loop for landing a change in Bevy: branch, code, test, PR, review, merge.

Branching

• Fork bevyengine/bevy on GitHub.
• Clone your fork. Add the upstream remote: git remote add upstream https://github.com/bevyengine/bevy.
• Create a topic branch off main: git checkout -b your-feature.

Bevy maintainers do not merge directly to main from forks of forks; PRs target the upstream main.

Coding

• Run cargo fmt regularly. The workspace rustfmt.toml enforces a small number of stylistic choices — mostly the defaults plus alphabetical imports.
• Follow the patterns and conventions page. The big ones: workspace lints flag missing_docs, unwrap_or_default, undocumented_unsafe_blocks, print_stdout, and print_stderr. Workspace-wide unsafe_code = "deny" means any new unsafe block must opt-in by allowing the lint and explaining why.
• Add tests close to the change. Inline #[cfg(test)] modules are the norm.
• Run cargo run -p ci -- check locally before pushing. It runs the same checks as CI and is much faster than waiting for a remote run.

Examples and docs

User-visible features need:

1. Rustdoc on the public API. The workspace lints missing_docs as a warn so a doc gap is visible.
2. An example under examples/ if the feature is end-user-facing. Examples are smoke-tested by CI via tools/example-showcase.
3. An entry in examples/README.md. This file is auto-generated; run cargo run -p build-templated-pages -- update examples after adding an [[example]] to the root Cargo.toml.

Migration guides and release notes

Breaking changes need an entry under _release-content/migration-guides/ (one markdown file per change). Significant features get an entry under _release-content/release-notes/. Both directories are processed at release time by tools/build-templated-pages.

Format example for a migration guide entry (_release-content/migration-guides/<short-name>.md):

---
title: New thing
pull_requests: [12345]
---

Old code:
\`\`\`rust
old_api_call();
\`\`\`

New code:
\`\`\`rust
new_api_call();
\`\`\`

Opening the PR

• Use the PR template. Keep the description short, factual, and oriented around what changed and why. Reviewers do not need a recap of the issue.
• Mark as draft if you want CI to run but you're not ready for review. Drafts skip the auto-review-request bot.
• Pin a specific issue in the PR body with Closes #1234 so it auto-closes on merge.

Labels

PRs get labels from the maintainers (or the welcome bot). The labels you'll see most:

• A-* (area) — what subsystem the PR touches (A-ECS, A-Rendering, A-Assets, etc).
• C-* (category) — bug, feature, refactor, performance.
• M-* (modifier) — M-Needs-Migration-Guide, M-Needs-Release-Note, M-Needs-Example.
• S-* (status) — S-Ready-For-Final-Review, S-Needs-Review, S-Blocked.

Review

A PR usually needs two approving reviews from people in the relevant area before merge. Areas with a single specialist (e.g. some niche audio or platform code) may merge with one approval at maintainer discretion.

Reviewers commonly ask for:

• Smaller commits or a clean rebase before merge.
• Better doc comments — Bevy's bar for rustdoc is high.
• A migration-guide entry if the PR touches the public API.
• A test that exercises the change.

Merging

The merge queue runs CI one more time, then merges via GitHub's merge queue. Squash merging is the default — the squash message is the PR title plus the PR body, so keep them tidy.

After merge:

• The change appears on main under the bevy tag (the project does not use long-running release branches; backports are explicit cherry-picks for point releases).
• If the PR was tagged M-Needs-Migration-Guide, the migration guide file you authored becomes part of the next minor release notes.

Backports

Critical fixes get backported to the latest released branch by maintainers. You don't need to open the backport PR yourself — flag it in the issue or PR description and a maintainer will handle it.