Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity
main
Blacksite/docs/adr/0002-bevy-version-and-migration-policy.md
Rbanh f29712d158
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Initial project import
2026-06-05 21:44:45 -04:00

1.6 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.18 with Avian 0.6, bevy_egui, bevy-inspector-egui, and transform-gizmo-bevy.

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.
  • 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.

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.