bevyengine / bevyengine/bevy-website
New features deserve migration guides
- Dominant language
- JavaScript
- Stars
- 249
- Forks
- 450
- Avg merge
- 16h 20m
- Merged PRs (30d)
- 6
Description
## Problem
Adding new features sometimes gates previously accessible types or functionality, this is a breaking change that should be documented in migration guides.
This is especially problematic when the new feature is a part of default features, meaning that it's much less likely to get caught as a breaking change (because it does not break projects who enable default features, only projects who specify their features manually).
### Example
When migrating to 0.15.0, my project failed to compile because of a missing `Window` type, which requires the new `bevy_window` feature.
## Solution
PRs that introduce new features should be mentioned in the migration guides, possibly even getting sections.
(Though it might be enough to have a single section that documents that new features have been added and that it might be necessary to evaluate them for your project.)
Contributor guide
Research direction
Start by reviewing the existing migration guides and PRs that introduce new features. Determine how manually specified features can gate previously available types or functionality, then document those breaking changes or establish the proposed general migration-guide section. Done means affected feature additions are consistently identified and explained to users.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100