Improve code examples in 0.18 migration guides

release-content/migration-guides/ambient_light_split.md

@@ -9,19 +9,15 @@ The resource `GlobalAmbientLight` is the default ambient light for the entire wo
 Meanwhile, `AmbientLight` is a component that can be added to a `Camera` in order to override the default `GlobalAmbientLight`.
 When appropriate, rename `AmbientLight` to `GlobalAmbientLight`.
 
-Before:
-
 ```rust
+// 0.17
 app.insert_resource(AmbientLight {
     color: Color::WHITE,
     brightness: 2000.,
     ..default()
 });
-```
 
-After:
-
-```rust
+// 0.18
 app.insert_resource(GlobalAmbientLight {
     color: Color::WHITE,
     brightness: 2000.,

release-content/migration-guides/animation-target-refactor.md

@@ -10,14 +10,10 @@ The `AnimationTarget` component has been split into two separate components.
 This change was made to add flexibility. It's now possible to calculate the
 `AnimationTargetId` first, but defer the choice of player until later.
 
-Before:
-
 ```rust
+// 0.17
 entity.insert(AnimationTarget { id: AnimationTargetId(id), player: player_entity });
-```
 
-After:
-
-```rust
+// 0.18
 entity.insert((AnimationTargetId(id), AnimatedBy(player_entity)));
 ```

release-content/migration-guides/archetype_query_data.md

@@ -15,6 +15,7 @@ Code that requires queries to `impl ExactSizeIterator` may need to replace `Quer
 fn requires_exact_size<D: QueryData>(q: Query<D>) -> usize {
     q.into_iter().len()
 }
+
 // 0.18
 fn requires_exact_size<D: ArchetypeQueryData>(q: Query<D>) -> usize {
     q.into_iter().len()

release-content/migration-guides/asset_watcher_async_sender.md

@@ -1,6 +1,6 @@
 ---
 title: AssetSources now give an `async_channel::Sender` instead of a `crossbeam_channel::Sender`
-pull_requests: []
+pull_requests: [21626]
 ---
 
 Previously, when creating an asset source, `AssetSourceBuilder::with_watcher` would provide users

release-content/migration-guides/bevy_input_features.md

@@ -11,12 +11,13 @@ If you use `bevy_window` or `bevy_gilrs`, they will automatically
 enable the necessary features on `bevy_input`. If you don't depend
 on them (for example, if you are developing for a platform that
 isn't supported by these crates), you need to enable the required
-input sources on `bevy_input` manually:
+input sources on the `bevy_input` / `bevy` crate manually:
 
 ```toml
-# Before:
+# 0.17
 bevy = { version = "0.17", default-features = false }
-# After (enable sources that you actually use):
+
+# 0.18 (enable sources that you actually use):
 bevy = { version = "0.18", default-features = false, features = [
   "mouse",
   "keyboard",

release-content/migration-guides/bindgroup-labels-mandatory.md

@@ -8,7 +8,12 @@ In previous versions of Bevy, the `label` of a `BindGroupLayout` was optional. T
 If you were previously omitting the `label` implementation from a `impl AsBindGroup`, you now must implement it:
 
 ```rust
-fn label() -> &'static str {
-    "my label"
+impl AsBindGroup for CoolMaterial {
+    // ...
+
+    fn label() -> &'static str {
+        // It is customary to make the label the name of the type.
+        "CoolMaterial"
+    }
 }
 ```

release-content/migration-guides/bundle_component_ids.md

@@ -6,9 +6,10 @@ pull_requests: [14791, 15458, 15269]
 `Bundle::component_ids` and `Bundle::get_component_ids` were changed to return an iterator over
 `ComponentId` and `Option<ComponentId>` respectively. In some cases this can avoid allocating.
 
+For implementors:
+
 ```rust
-// For implementors
-// Before
+// 0.17
 unsafe impl<C: Component> Bundle for C {
     fn component_ids(components: &mut ComponentsRegistrator, ids: &mut impl FnMut(ComponentId)) {
         ids(components.register_component::<C>());
@@ -19,7 +20,7 @@ unsafe impl<C: Component> Bundle for C {
     }
 }
 
-// After
+// 0.18
 unsafe impl<C: Component> Bundle for C {
     fn component_ids<(
         components: &mut ComponentsRegistrator,
@@ -34,14 +35,15 @@ unsafe impl<C: Component> Bundle for C {
 }
 ```
 
+For consumers:
+
 ```rust
-// For Consumers
-// Before
+// 0.17
 let mut components = vec![];
 MyBundle::component_ids(&mut world.components_registrator(), &mut |id| {
     components.push(id);
 });
 
-// After
+// 0.18
 let components: Vec<_> = B::component_ids(&mut world.components_registrator()).collect();
 ```

release-content/migration-guides/changed_asset_server_init.md

@@ -3,57 +3,36 @@ title: Changes to `AssetServer` and `AssetProcessor` creation.
 pull_requests: [21763]
 ---
 
-Previously `AssetServer`s `new` methods would take `AssetSources`. Now, these methods take
-`Arc<AssetSources>`. So if you previously had:
+Previously `AssetServer`s `new` and `new_with_method_check` methods would take `AssetSources`. Now, these methods take
+`Arc<AssetSources>`.
 
 ```rust
+// 0.17
 AssetServer::new(
     sources,
     mode,
     watching_for_changes,
     unapproved_path_mode,
 )
 
-// OR:
-AssetServer::new_with_meta_check(
-    sources,
-    mode,
-    meta_check,
-    watching_for_changes,
-    unapproved_path_mode,
-)
-```
-
-Now you need to do:
-
-```rust
+// 0.18
 AssetServer::new(
+    // Wrap the sources in an `Arc`.
     Arc::new(sources),
     mode,
     watching_for_changes,
     unapproved_path_mode,
 )
-
-// OR:
-AssetServer::new_with_meta_check(
-    Arc::new(sources),
-    mode,
-    meta_check,
-    watching_for_changes,
-    unapproved_path_mode,
-)
 ```
 
 `AssetProcessor::new` has also changed. It now returns to you the `Arc<AssetSources>` which can (and
-should) be shared with the `AssetServer`. So if you previously had:
+should) be shared with the `AssetServer`.
 
 ```rust
+// 0.17
 let processor = AssetProcessor::new(sources);
-```
 
-Now you need:
-
-```rust
+// 0.18
 let (processor, sources_arc) = AssetProcessor::new(
     sources,
     // A bool whether the returned sources should listen for changes as asset processing completes.

release-content/migration-guides/combinator_system.md

@@ -3,12 +3,41 @@ title: System Combinators
 pull_requests: [20671]
 ---
 
-The `CombinatorSystem`s can be used to combine multiple `SystemCondition`s with logical operators. Previously, the conditions would short circuit if the system failed to run, for example because it's query could not be filled by the world.
+`CombinatorSystem`s can be used to combine multiple `SystemCondition`s with logical operators (such as `and`, `or`, and `xor`). Previously, these combinators would propagate any errors made when running the combined systems:
 
-Now, the `CombinatorSystem`s will work as expected, following the semantics of rust's logical operators.
-Namely, if a `SystemCondition` fails, it will be considered to have returned `false` and in combinators that don't short circuit the other condition will now be run.
+```rust
+// 0.17
+#[derive(Component)]
+struct Foo;
+
+// This run condition will fail validation because there is not an entity with `Foo` in the world.
+fn fails_validation(_: Single<&Foo>) -> bool {
+    // ...
+}
+
+fn always_true() -> bool {
+    true
+}
+
+let mut world = World::new();
 
-Specifically, the combinators act as follows:
+// Because `fails_validation` is invalid, trying to run this combinator system will return an
+// error.
+assert!(world.run_system_once(fails_validation.or(always_true)).is_err());
+```
+
+This behavior has been changed in Bevy 0.18. Now if one of the combined systems fails, it will be considered to have returned `false`. The error will not be propagated, and the combinator logic will continue:
+
+```rust
+// 0.18
+let mut world = World::new();
+
+// `fails_validation` is invalid, but it is converted to `false`. Because `always_true` succeeds,
+// the combinator returns `true`.
+assert_eq!(matches!(world.run_system_once(fails_validation.or(always_true)), Ok(true)));
+```
+
+This affects the following combinators:
 
 | Combinator | Rust Equivalent |
 |:----------:|:---------------:|
@@ -18,21 +47,3 @@ Specifically, the combinators act as follows:
 | `nand`     | `!(a && b)`     |
 | `nor`      | `!(a \|\| b)`   |
 | `xnor`     | `!(a ^ b)`      |
-
-```rust
-fn vacant(_: crate::system::Single<&Vacant>) -> bool {
-    true
-}
-
-fn is_true() -> bool {
-    true
-}
-
-assert!(world.query::<&Vacant>().iter(&world).next().is_none());
-
-// previously:
-assert!(world.run_system_once(is_true.or(vacant)).is_err());
-
-// now:
-assert!(matches!(world.run_system_once(is_true.or(vacant)), Ok(true)));
-```

release-content/migration-guides/custom_asset_source_infallible.md

@@ -7,22 +7,17 @@ Previously, it was possible to create asset sources with no reader, resulting in
 silently being skipped. This is no longer possible, since `AssetSourceBuilder` must now be given a
 reader to start. We also slightly changed how sources are expected to be built.
 
-In previous versions, creating a custom source would look like:
-
 ```rust
+// 0.17
 AssetSource::build()
-    .with_reader(move || todo!("the reader!"))
-    .with_writer(move || todo!())
-    .with_processed_reader(move || todo!())
-    .with_processed_writer(move || todo!())
-```
+    .with_reader(move || /* reader logic */)
+    .with_writer(move || /* ... */)
+    .with_processed_reader(move || /* ... */)
+    .with_processed_writer(move || /* ... */);
 
-In Bevy 0.18, this now looks like:
-
-```rust
-// You may need to import AssetSourceBuilder.
-AssetSourceBuilder::new(move || todo!("the reader!"))
-    .with_writer(move || todo!())
-    .with_processed_reader(move || todo!())
-    .with_processed_writer(move || todo!())
+// 0.18
+AssetSourceBuilder::new(move || /* reader logic */)
+    .with_writer(move || /* ... */)
+    .with_processed_reader(move || /* ... */)
+    .with_processed_writer(move || /* ... */;
 ```

release-content/migration-guides/derive_compile_error_for_non_static_resource.md

@@ -6,8 +6,7 @@ pull_requests: [21385]
 Any type with `#[derive(Resource)]` that uses non-static lifetime will no longer compile.
 
 ```rust
-// Will no longer compile in 0.18,
-// 'a should be 'static
+// Will no longer compile in 0.18, `'a` should be `'static`.
 #[derive(Resource)]
 struct Foo<'a> {
    bar: &'a str

release-content/migration-guides/enable_prepass.md

@@ -9,13 +9,13 @@ been replaced by the `Material` methods `enable_prepass` and `enable_shadows`.
 Analogous methods have also been added to `MaterialExtension`
 
 ```rust
-/// before
+// 0.17
 MaterialPlugin::<MyMaterial> {
     prepass_enabled: false,
     shadows_enabled: false,
 }
 
-/// after
+// 0.18
 impl Material for MyMaterial {
     /// ...
 

release-content/migration-guides/generalized_atmosphere.md

@@ -7,21 +7,31 @@ pull_requests: [20838]
 Most of the fields on `Atmosphere` have been removed in favor of a handle
 to the new `ScatteringMedium` asset.
 
-```diff
+```rust
+// 0.17
+pub struct Atmosphere {
+    pub bottom_radius: f32,
+    pub top_radius: f32,
+    pub ground_albedo: Vec3,
+    // All of these fields have been removed.
+    pub rayleigh_density_exp_scale: f32,
+    pub rayleigh_scattering: Vec3,
+    pub mie_density_exp_scale: f32,
+    pub mie_scattering: f32,
+    pub mie_absorption: f32,
+    pub mie_asymmetry: f32,
+    pub ozone_layer_altitude: f32,
+    pub ozone_layer_width: f32,
+    pub ozone_absorption: Vec3,
+}
+
+// 0.18
 pub struct Atmosphere {
     pub bottom_radius: f32,
     pub top_radius: f32,
     pub ground_albedo: Vec3,
-+   pub medium: Handle<ScatteringMedium>,
--   pub rayleigh_density_exp_scale: f32,
--   pub rayleigh_scattering: Vec3,
--   pub mie_density_exp_scale: f32,
--   pub mie_scattering: f32,
--   pub mie_absorption: f32,
--   pub mie_asymmetry: f32,
--   pub ozone_layer_altitude: f32,
--   pub ozone_layer_width: f32,
--   pub ozone_absorption: Vec3,
+    // This replaces all of the old fields.
+    pub medium: Handle<ScatteringMedium>,
 }
 ```
 

release-content/migration-guides/gltf-coordinate-conversion.md

@@ -25,16 +25,20 @@ In 0.18 there are two changes. Firstly, the `use_model_forward_direction` option
 has been renamed to `convert_coordinates`, and is now a struct with two separate
 options.
 
-```diff
- struct GltfPlugin {
-     ...
--    use_model_forward_direction: bool,
-+    convert_coordinates: GltfConvertCoordinates,
- }
-```
-
 ```rust
-struct GltfConvertCoordinates {
+// 0.17
+pub struct GltfPlugin {
+    use_model_forward_direction: bool,
+    // ...
+}
+
+// 0.18
+pub struct GltfPlugin {
+    convert_coordinates: GltfConvertCoordinates,
+    // ...
+}
+
+pub struct GltfConvertCoordinates {
     rotate_scene_entity: bool,
     rotate_meshes: bool,
 }