bevyengine / bevyengine/bevy-website

New features deserve migration guides

Open
#1,888 1 comment 0 reactions 0 assignees View on GitHub
A-Migration Guides C-Content
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.