Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/renderer-material-component-foundation
Blacksite/docs/adr/0002-bevy-version-and-migration-policy.md
Rbanh b5e561904c
Some checks failed
CI / Format, lint, test, build (push) Has been cancelled
Details
Upgrade to Bevy 0.19 and harden editor workflows
2026-07-09 23:43:47 -04:00

2.0 KiB
Raw Permalink Blame History

ADR 0002: Bevy Version And Migration Policy

Status

Accepted

Context

Bevy moves quickly, and the project depends on ecosystem crates that track Bevy on their own schedules. The current workspace targets Bevy 0.19 with Avian 0.7, bevy_egui, bevy-inspector-egui, and local compatibility patches for transform-gizmo-bevy and bevy_ufbx.

Unplanned upgrades can break editor work, rendering, scene serialization, physics, and later networking. Delayed upgrades can also make migrations larger and riskier.

Decision

Use the latest stable Bevy release that is supported by the required ecosystem crates for the active milestone. Review Bevy upgrades on a scheduled release cadence instead of opportunistically changing versions during feature work.

Before merging a Bevy upgrade:

  • Confirm matching versions exist for editor, physics, and networking-related crates used by the active milestone.
  • Read Bevy migration guides for every skipped release.
  • Preserve authored scene compatibility when Bevy renames runtime scene components or serialization types.
  • Run cargo fmt --check, cargo check --workspace, cargo clippy --workspace, strict clippy on changed/foundation crates with -D warnings, focused tests for changed crates, and focused binary builds.
  • Smoke-test the game and editor manually after CI is green.
  • Record any project-specific migration notes in docs or ADR follow-ups.
  • Keep the normal development profile fully debuggable. Use line-table-only debug information and no incremental cache for the test profile so Bevy upgrade matrices do not retain multi-gigabyte test images indefinitely; use the indexed target cleanup workflow in the root README after migration passes.

Consequences

Feature branches should not upgrade Bevy unless the upgrade is their explicit scope. This reduces churn for parallel editor/gameplay work and keeps CI failures easier to attribute.

The project can still adopt new Bevy releases quickly, but the upgrade is treated as a focused compatibility task with verification and manual runtime checks.