Migration writing pass 3 (#2079)

Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: Tim Overbeek <[email protected]>

Author: 3 people

content/learn/migration-guides/0.15-to-0.16.md

@@ -12,6 +12,6 @@ This guide is currently for a __Release Candidate__ and is subject to change as
 
 The most important changes to be aware of this release are:
 
-- Bevy has reworked its error handling to make it easier to handle `Result`s everywhere. As a result, `Query::single` and friends now return results, rather than panicking.
+- Bevy now prefers `Result`s over panicking, as applications can easily recover from `Result`s instead of crashing. As part of this decision, Bevy's error handling capabilities have been significantly improved. (Systems can easily return `Result`s and a new `BevyError` type has been introduced.) Additionally, several panicking functions have been switched to return a result (`Query::single()`) or have been deprecated completely (`Query::many()`).
 
 {{ migration_guides(version="0.16") }}

release-content/0.16/migration-guides/15858_Introduce_methods_on_QueryState_to_obtain_a_Query.md

@@ -1 +1 @@
-`Query::to_readonly` has been renamed to `Query::as_readonly`.
+`Query::to_readonly()` has been renamed to `Query::as_readonly()` to reflect that it is cheap to call.

release-content/0.16/migration-guides/16219_Flush_commands_after_every_mutation_in_WorldEntityMut.md

@@ -1,3 +1,3 @@
-Previously `EntityWorldMut` triggered command queue flushes in unpredictable places, which could interfere with hooks and observers. Now the command queue is flushed always immediately after any call in `EntityWorldMut` that spawns or despawns an entity, or adds, removes or replaces a component. This means hooks and observers will run their commands in the correct order.
+Previously, `EntityWorldMut` triggered command queue flushes in unpredictable places, which could interfere with hooks and observers. Now the command queue is always flushed immediately after `EntityWorldMut` spawns or despawns an entity, or adds, removes, or replaces a component.
 
-As a side effect, there is a possibility that a hook or observer could despawn the entity that is being referred to by `EntityWorldMut`. This could already currently happen if an observer was added while keeping an `EntityWorldMut` reference and would cause unsound behaviour. If the entity has been despawned, calling any methods which require the entity location will panic. This matches the behaviour that `Commands` will panic if called on an already despawned entity. In the extremely rare case where taking a new `EntityWorldMut` reference or otherwise restructuring the code so that this case does not happen is not possible, there’s a new `is_despawned` method that can be used to check if the referred entity has been despawned.
+As a side effect of this change, there is a new possibility that a hook or observer may despawn an entity that is being referred to by `EntityWorldMut`. If any of `EntityWorldMut`'s methods detect that the entity is despawned, they will panic. If you know this is a possibility and wish to avoid panicking, you may check that the entity is despawned with `EntityWorldMut::is_despawned()`.

release-content/0.16/migration-guides/16589_Fallible_systems.md

@@ -1,8 +1,7 @@
-Users who have implemented their own custom executor should use `ScheduleSystem` in place of `BoxedSystem<(), ()>` and import the `System` trait where needed. 
+If you've written a custom executor, there are a few changes you will need to make in order to support fallible systems.
 
-Custom executors should:
+1. Many uses of `BoxedSystem<(), ()>` have been replaced with `ScheduleSystem`, which is a type alias to `BoxedSystem<(), Result>`.
+2. Executors should obey the `SystemParamValidationError` returned by `SystemParam::validate_param()` in order to determine whether to raise an error or skip the system.
+3. When an executor encounters an error, it should pass that error to `default_error_handler()`, whose behavior can be configured with the `GLOBAL_ERROR_HANDLER` static.
 
-- obey the `SystemParamValidationError` returned by `SystemParam::validate_param`, skipping systems as requested
-- use the `default_error_handler` for both validation errors and results returned from systems
-
-See the source code of the first-party Bevy schedule executors for more details.
+For more information on fallible systems, please read the module docs for `bevy::ecs::error`.

release-content/0.16/migration-guides/17215_Improved_Command_Errors.md

@@ -1 +1,31 @@
-<!-- TODO -->
+The `EntityCommands::apply()` method now takes a `EntityWorldMut`, which is an optimized version of the previous `Entity` and `&mut World` pair. `EntityWorldMut` has several existing methods for working with entities, although you may use `EntityWorldMut::id()` to access the `Entity` and `EntityWorldMut::world_scope()` to access the `&mut World`.
+
+```rust
+struct MyCommand;
+
+fn print_entity(In(entity): In<Entity>) {
+    info!("Entity: {entity}");
+}
+
+// 0.15
+impl EntityCommand for MyCommand {
+    fn apply(self, entity: Entity, world: &mut World) {
+        world
+            .run_system_cached_with(print_entity, entity)
+            .unwrap();
+    }
+}
+
+// 0.16
+impl EntityCommand for MyCommand {
+    fn apply(self, entity_world: EntityWorldMut) {
+        let entity = entity_world.id();
+
+        entity_world.world_scope(move |world: &mut World| {
+            world.run_system_cached_with(print_entity, entity).unwrap();
+        });
+    }
+}
+```
+
+Additionally, the method `EntityCommand::with_entity()` has been moved to a separate trait, `CommandWithEntity`, so that it can be generic over commands that return `Result`s.

release-content/0.16/migration-guides/17521_Improved_Spawn_APIs_and_Bundle_Effects.md

@@ -1,23 +1,15 @@
-Existing spawn patterns will continue to work as expected.
-
-Manual Bundle implementations now require a `BundleEffect` associated type. Existing bundles would have no bundle effect, so use `()`. Additionally `Bundle::from_components` has been moved to the new `BundleFromComponents` trait.
+As part of improvements to the bundle spawning API, the `DynamicBundle` trait now has a new `Effect` associated type. If you manually implemented `DynamicBundle`, you likely want to set `Effect = ()`, which retains the same behavior as 0.15 bundles:
 
 ```rust
-// Before
-unsafe impl Bundle for X {
-    unsafe fn from_components<T, F>(ctx: &mut T, func: &mut F) -> Self {
-    }
-    /* remaining bundle impl here */
+// 0.15
+impl DynamicBundle for MyBundle {
+    // ...
 }
 
-// After
-unsafe impl Bundle for X {
+// 0.16
+impl DynamicBundle for MyBundle {
     type Effect = ();
-    /* remaining bundle impl here */
-}
 
-unsafe impl BundleFromComponents for X {
-    unsafe fn from_components<T, F>(ctx: &mut T, func: &mut F) -> Self {
-    }
+    // ...
 }
 ```

release-content/0.16/migration-guides/17602_Encapsulate_cfgfeature__track_location_in_a_type.md

@@ -1,7 +1,7 @@
-Methods like `Ref::changed_by()` that return a `&'static Location<'static>` will now be available even when the `track_location` feature is disabled, but they will return a new `MaybeLocation` type.  `MaybeLocation` wraps a `&'static Location<'static>` when the feature is enabled, and is a ZST when the feature is disabled.
+Methods like `Ref::changed_by()` that used to return a `&'static Location<'static>` will now be available even when the `track_location` feature is disabled, but they will now return the new `MaybeLocation` type. `MaybeLocation` wraps a `&'static Location<'static>` when the feature is enabled, and is a ZST when the feature is disabled.
 
-Existing code that needs a `&Location` can call `into_option().unwrap()` to recover it.  Many trait impls are forwarded, so if you only need `Display` then no changes will be necessary.
+Existing code that needs a `&Location` can call `MaybeLocation::into_option()` to recover it. Many trait impls are forwarded, so if you only need `Display` then no changes will be necessary.
 
 If that code was conditionally compiled, you may instead want to use the methods on `MaybeLocation` to remove the need for conditional compilation.
 
-Code that constructs a `Ref`, `Mut`, `Res`, or `ResMut` will now need to provide location information unconditionally.  If you are creating them from existing Bevy types, you can obtain a `MaybeLocation` from methods like `Table::get_changed_by_slice_for()` or `ComponentSparseSet::get_with_ticks`.  Otherwise, you will need to store a `MaybeLocation` next to your data and use methods like `as_ref()` or `as_mut()` to obtain wrapped references.
+Code that constructs a `Ref`, `Mut`, `Res`, or `ResMut` will now need to provide location information unconditionally.  If you are creating them from existing Bevy types, you can obtain a `MaybeLocation` from methods like `Table::get_changed_by_slice_for()` or `ComponentSparseSet::get_with_ticks`. Otherwise, you will need to store a `MaybeLocation` next to your data and use methods like `as_ref()` or `as_mut()` to obtain wrapped references.

release-content/0.16/migration-guides/17671_Isolate_component_registration.md

@@ -1,2 +1,8 @@
-- Remove storages from functions where it is no longer needed.
-- Note that SparseSets are no longer present for all registered sparse set components, only those that have been spawned.
+In order to decouple `Storages` from `Components`, the following methods no longer take a `&mut Storages` argument:
+
+- `Components::register_component()`
+- `Components::register_component_with_descriptor()`
+- `Bundle::register_required_components()`
+- `Component::register_required_components()`
+
+With this change, note that `SparseSets` will no longer be created when components are registered. Instead, they will only be constructed when those components are spawned.

release-content/0.16/migration-guides/17826_Fix_unsoundness_in_QueryItersort_by.md

@@ -1,15 +1,41 @@
-The `sort` family of methods on `QueryIter` unsoundly gave access `L::Item<'w>` with the full `'w` lifetime.  It has been shortened to `L::Item<'w>` so that items cannot escape the comparer.  If you get lifetime errors using these methods, you will need to make the comparer generic in the new lifetime.  Often this can be done by replacing named `'w` with `'_`, or by replacing the use of a function item with a closure.
+The `sort()` family of methods on `QueryIter` unsoundly gave access `L::Item<'w>` with the full world `'w` lifetime, meaning it was possible to smuggle items out of the compare closure. This has been fixed by shortening the lifetime so that items cannot escape the closure on the following methods on `QueryIter` and `QueryManyIter`:
+
+- `sort()`
+- `sort_unstable()`
+- `sort_by()`
+- `sort_unstable_by()`
+- `sort_by_key()`
+- `sort_unstable_by_key()`
+- `sort_by_cached_key()`
+
+This fix may cause your code to get lifetimes errors, such as:
+
+```
+error: implementation of `FnMut` is not general enough
+```
+
+To fix this, you will need to make the comparer generic over the new lifetime. Often this can be done by replacing named `'w` with `'_`, or by replacing the use of a function item with a closure:
 
 ```rust
-// Before: Now fails with "error: implementation of `FnMut` is not general enough"
+// 0.15
 query.iter().sort_by::<&C>(Ord::cmp);
-// After: Wrap in a closure
+
+// 0.16
 query.iter().sort_by::<&C>(|l, r| Ord::cmp(l, r));
+```
+
+```rust
+// 0.15
+fn comparer(left: &&'w C, right: &&'w C) -> Ordering {
+    // ...
+}
+
+query.iter().sort_by::<&C>(comparer);
+
+// 0.16
+fn comparer(left: &&C, right: &&C) -> Ordering {
+    // ...
+}
 
 query.iter().sort_by::<&C>(comparer);
-// Before: Uses specific `'w` lifetime from some outer scope
-// now fails with "error: implementation of `FnMut` is not general enough"
-fn comparer(left: &&'w C, right: &&'w C) -> Ordering { /* ... */ }
-// After: Accepts any lifetime using inferred lifetime parameter
-fn comparer(left: &&C, right: &&C) -> Ordering { /* ... */ }
 ```

release-content/0.16/migration-guides/17962_Generic_system_config.md

@@ -1,4 +1,8 @@
-SystemSetConfigs -> ScheduleConfigs<InternedSystemSet>
-SystemConfigs -> ScheduleConfigs<ScheduleSystem>
-IntoSystemSetConfigs -> IntoScheduleConfigs<InternedSystemSet, M>
-IntoSystemConfigs -> IntoScheduleConfigs<ScheduleSystem, M>
+In order to reduce internal duplication between scheduling systems and system sets, the new generic `ScheduleConfigs<T>` type and `IntoScheduleConfigs<T>` trait have been added. These take a generic parameter, `T`, that may be `ScheduleSystem` (for systems) or `InternedSystemSet` (for system sets).
+
+|0.15 Item|0.16 Item|
+|-|-|
+|`SystemConfigs`|`ScheduleConfigs<ScheduleSystem>`|
+|`SystemSetConfigs`|`ScheduleConfigs<InternedSystemSet>`|
+|`IntoSystemConfigs`|`IntoScheduleConfigs<ScheduleSystem, M>`|
+|`IntoSystemSetConfigs`|`IntoScheduleConfigs<InternedSystemSet, M>`|