Migration writing pass 5 (#2094)

Author: BD103

release-content/0.16/migration-guides/15624_Support_using_FilteredResources_with_ReflectResource.md

@@ -1 +1,8 @@
-The order of hooks and observers for `on_replace` and `on_remove` has been swapped. Observers are now run before hooks. This is a more natural ordering where the removal ordering is inverted compared to the insertion ordering.
+The order of hooks and observers for `on_replace()` and `on_remove()` has been swapped, so now observers are run before hooks. As hooks are more primitive, they are designated as the first and last thing run when a component is added and removed. The total order for component removal can now be seen in the following table:
+
+|0.15|0.16|
+|-|-|
+|`on_replace()` hook|`on_replace()` observer|
+|`on_replace()` observer|`on_replace()` hook|
+|`on_remove()` hook|`on_remove()` observer|
+|`on_remove()` observer|`on_remove()` hook|

release-content/0.16/migration-guides/16499_Run_observers_before_hooks_for_on_replace_and_on_remove.md

@@ -1 +1 @@
-- If you were previously calling the special `apply_deferred` system via `apply_deferred(world)`, don’t.
+The special `apply_deferred()` system has been converted into the zero-sized `ApplyDeferred` type that implements `System` for performance reasons. If you manually schedule `apply_deferred()`, which usually isn't the case, you will need to use the new `ApplyDeferred` type instead. If you manually called `apply_deferred()` without your code, you may delete it, as that function did nothing.

release-content/0.16/migration-guides/16642_Turn_apply_deferred_into_a_ZST_System.md

@@ -1 +1,9 @@
-`EntityHashSet` and `EntityHashMap` are no longer re-exported in `bevy_ecs::entity` directly. If you were not using `bevy_ecs` / `bevy`’s `prelude`, you can access them through their now-public modules, `hash_set` and `hash_map` instead.
+`EntityHashSet` and `EntityHashMap` are no longer re-exported in `bevy::ecs::entity`, although they are still accessible through the prelude. If you were directly importing `EntityHashSet` and `EntityHashMap`, please access them from `bevy::ecs::entity::hash_set` and `bevy::ecs::entity::hash_map`.
+
+```rust
+// 0.15
+use bevy::ecs::entity::{HashSet, HashMap};
+
+// 0.16
+use bevy::ecs::entity::{hash_set::HashSet, hash_map::HashMap};
+```

release-content/0.16/migration-guides/17447_Support_nonVec_data_structures_in_relations.md

@@ -1,19 +1,21 @@
-`Component::register_component_hooks` is now deprecated and will be removed in a future release. When implementing `Component` manually, also implement the respective hook methods on `Component`.
+Component hook registration is now split out into individual methods of `Component`. The original `Component::register_component_hooks()` has been deprecated, so please switch to the new `Component::on_add()`, `Component::on_remove()`, and related methods.
 
 ```rust
-// Before
+// 0.15
 impl Component for Foo {
-    // snip
     fn register_component_hooks(hooks: &mut ComponentHooks) {
-            hooks.on_add(foo_on_add);
+        hooks.on_add(foo_on_add);
     }
+
+    // ...
 }
 
-// After
+// 0.16
 impl Component for Foo {
-    // snip
     fn on_add() -> Option<ComponentHook> {
-            Some(foo_on_add)
+        Some(foo_on_add)
     }
+
+    // ...
 }
 ```

release-content/0.16/migration-guides/17685_Split_Componentregister_component_hooks_into_individual_me.md

@@ -1 +1,3 @@
-Users of `QueryLens::query()` who were calling `get_inner()` or `iter_inner()` will need to replace the call with `QueryLens::query_inner()`.
+There was a lifetime issue found with `QueryLens::query()` where calling `get_inner()` on the returned value would allow for multiple mutable references to the same entity. This has been fixed by shrinking the lifetime of `QueryLens::query()`'s result, however it may break existing code.
+
+If you run into lifetime issues while calling `get_inner()` or `iter_inner()` on `QueryLens::query()`'s result, you may need to switch to the new `QueryLens::query_inner()` method that only works on immutable queries.

release-content/0.16/migration-guides/17694_Shorten_the_world_lifetime_returned_from_QueryLensquery.md

@@ -1,3 +1,7 @@
-- `EventWriter::send` has been renamed to `EventWriter::write`.
-- `EventWriter::send_batch` has been renamed to `EventWriter::write_batch`.
-- `EventWriter::send_default` has been renamed to `EventWriter::write_default`.
+`EventWriter::send()` and its family of methods have been renamed to `EventWriter::write()` in order to reduce confusion and increase consistency. The old methods have been deprecated.
+
+|0.15|0.16|
+|-|-|
+|`EventWriter::send()`|`EventWriter::write()`|
+|`EventWriter::send_batch()`|`EventWriter::write_batch()`|
+|`EventWriter::send_default()`|`EventWriter::write_default()`|

release-content/0.16/migration-guides/17977_Renamed_EventWritersend_methods_to_write.md

@@ -1,23 +1,17 @@
-`RequiredComponents::register_dynamic` has been changed to `RequiredComponents::register_dynamic_with`.
-
-Old:
+`RequiredComponents::register_dynamic()` has been replaced by `RequiredComponents::register_dynamic_with()`, which avoids unnecessary cloning.
 
 ```rust
+// 0.15
 required_components.register_dynamic(
-      component_id,
-      component_constructor.clone(),
-      requirement_inheritance_depth,
+    component_id,
+    component_constructor.clone(),
+    requirement_inheritance_depth,
 );
-```
-
-New:
 
-```rust
+// 0.16
 required_components.register_dynamic_with(
-      component_id,
-      requirement_inheritance_depth,
-      || component_constructor.clone(),
+    component_id,
+    requirement_inheritance_depth,
+    || component_constructor.clone(),
 );
 ```
-
-This can prevent unnecessary cloning.

release-content/0.16/migration-guides/18028_Use_register_dynamic_for_merging.md

@@ -1,19 +1,25 @@
-If you were previously implementing `VisitEntities` or `VisitEntitiesMut` (likely via a derive), instead use `MapEntities`. Those were almost certainly used in the context of Bevy Scenes or reflection via `ReflectMapEntities`. If you have a case that uses `VisitEntities` or `VisitEntitiesMut` directly, where `MapEntities` is not a viable replacement, please let us know!
+`VisitEntities` and `VisitEntitiesMut` have been removed in favor of `MapEntities`, as the prior is less generally applicable (doesn't work on collections like `HashSet`s). If you previously derived `VisitEntities` and family, you can now derive `MapEntities` and use the `#[entities]` attribute to annotate the list of `Entity`s.
 
 ```rust
-// before
+// 0.15
 #[derive(VisitEntities, VisitEntitiesMut)]
 struct Inventory {
-  items: Vec<Entity>,
-  #[visit_entities(ignore)]
-  label: String,
+    items: Vec<Entity>,
+    // Opt-out of mapping this field, as its a string.
+    #[visit_entities(ignore)]
+    label: String,
 }
 
-// after
+// 0.16
 #[derive(MapEntities)]
 struct Inventory {
-  #[entities]
-  items: Vec<Entity>,
-  label: String,
+    // Opt-in to mapping this field.
+    #[entities]
+    items: Vec<Entity>,
+    label: String,
 }
 ```
+
+Note `Component::visit_entities()` and `Component::visit_entities_mut()` have also been removed in favor of the new `Component::map_entities()` method. When deriving `Component`, you may also use `#[entities]` to specify which `Entity`s may be mapped.
+
+Finally, entity mapping is no longer implemented for all types that implement `IntoIterator<Item = &Entity>`. If you previously depended on a custom data type to support the `#[entities]` attribute, please manually derive / implement `MapEntities` for it.

release-content/0.16/migration-guides/18432_Replace_VisitEntities_with_MapEntities.md

@@ -317,7 +317,7 @@ areas = ["ECS"]
 file_name = "16911_Remove_unused_generic_in_DeferredWorldtrigger.md"
 
 [[guides]]
-title = "Renamed `EventWriter::send` methods to `write`."
+title = "Rename `EventWriter::send()` methods to `write()`"
 prs = [17977]
 areas = ["ECS"]
 file_name = "17977_Renamed_EventWritersend_methods_to_write.md"
@@ -329,43 +329,37 @@ areas = ["ECS"]
 file_name = "18432_Replace_VisitEntities_with_MapEntities.md"
 
 [[guides]]
-title = "Run observers before hooks for `on_replace` and `on_remove`"
+title = "Run observers before hooks for `on_replace()` and `on_remove()`"
 prs = [16499]
 areas = ["ECS"]
 file_name = "16499_Run_observers_before_hooks_for_on_replace_and_on_remove.md"
 
 [[guides]]
-title = "Shorten the 'world lifetime returned from `QueryLens::query()`."
+title = "Shorten the lifetime returned from `QueryLens::query()`"
 prs = [17694]
 areas = ["ECS"]
 file_name = "17694_Shorten_the_world_lifetime_returned_from_QueryLensquery.md"
 
 [[guides]]
-title = "Split `Component::register_component_hooks` into individual methods"
+title = "Split `Component::register_component_hooks()` into individual methods"
 prs = [17685]
 areas = ["ECS"]
 file_name = "17685_Split_Componentregister_component_hooks_into_individual_me.md"
 
 [[guides]]
-title = "Support non-Vec data structures in relations"
+title = "Don't re-export `EntityHashSet` and `EntityHashMap`"
 prs = [17447]
 areas = ["ECS"]
 file_name = "17447_Support_nonVec_data_structures_in_relations.md"
 
 [[guides]]
-title = "Support using FilteredResources with ReflectResource."
-prs = [15624]
-areas = ["ECS"]
-file_name = "15624_Support_using_FilteredResources_with_ReflectResource.md"
-
-[[guides]]
-title = "Turn `apply_deferred` into a ZST System"
+title = "Turn `apply_deferred()` into a ZST system"
 prs = [16642]
 areas = ["ECS"]
 file_name = "16642_Turn_apply_deferred_into_a_ZST_System.md"
 
 [[guides]]
-title = "Use register_dynamic for merging"
+title = "Replace `register_dynamic()` with `register_dynamic_with()`"
 prs = [18028]
 areas = ["ECS"]
 file_name = "18028_Use_register_dynamic_for_merging.md"