32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# 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.
|