From 3f425da66e65c08933f43240a18c3c11981f45df Mon Sep 17 00:00:00 2001 From: kivi Date: Sat, 14 Sep 2024 23:03:21 +0200 Subject: [PATCH] =?UTF-8?q?Improve=20schedule=20note=20of=20.after/.before?= =?UTF-8?q?=20&=20encourage=20to=20use=20.chain=20ins=E2=80=A6=20(#14986)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Objective - Fixes #14552 - Make the current note of `before` and `after` understandable. - > The given set is not implicitly added to the schedule when this system set is added. ## Solution - Replace note in docs of [`after` and `before`](https://docs.rs/bevy/latest/bevy/ecs/prelude/trait.IntoSystemConfigs.html#method.before) - Note of after was removed completely, and links to `before`, because they notes would be identical. - Also encourage to use `.chain`, which is much simpler and safer to use ## Testing - Checked the docs after running `cargo doc` and `cargo run -p ci -- lints` - Are there any parts that need more testing? - no need to test, but please review the text. If it is still including the intended message and especially if its understandable. --------- Co-authored-by: Jan Hohenheim Co-authored-by: Alice Cecile --- crates/bevy_ecs/src/schedule/config.rs | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/crates/bevy_ecs/src/schedule/config.rs b/crates/bevy_ecs/src/schedule/config.rs index 55f38ca19c..96ab05d4eb 100644 --- a/crates/bevy_ecs/src/schedule/config.rs +++ b/crates/bevy_ecs/src/schedule/config.rs @@ -311,8 +311,8 @@ where /// If automatically inserting [`apply_deferred`](crate::schedule::apply_deferred) like /// this isn't desired, use [`before_ignore_deferred`](Self::before_ignore_deferred) instead. /// - /// Note: The given set is not implicitly added to the schedule when this system set is added. - /// It is safe, but no dependencies will be created. + /// Calling [`.chain`](Self::chain) is often more convenient and ensures that all systems are added to the schedule. + /// Please check the [caveats section of `.after`](Self::after) for details. fn before(self, set: impl IntoSystemSet) -> SystemConfigs { self.into_configs().before(set) } @@ -323,8 +323,23 @@ where /// If automatically inserting [`apply_deferred`](crate::schedule::apply_deferred) like /// this isn't desired, use [`after_ignore_deferred`](Self::after_ignore_deferred) instead. /// - /// Note: The given set is not implicitly added to the schedule when this system set is added. - /// It is safe, but no dependencies will be created. + /// Calling [`.chain`](Self::chain) is often more convenient and ensures that all systems are added to the schedule. + /// + /// # Caveats + /// + /// If you configure two [`System`]s like `(GameSystem::A).after(GameSystem::B)` or `(GameSystem::A).before(GameSystem::B)`, the `GameSystem::B` will not be automatically scheduled. + /// + /// This means that the system `GameSystem::A` and the system or systems in `GameSystem::B` will run independently of each other if `GameSystem::B` was never explicitly scheduled with [`configure_sets`] + /// If that is the case, `.after`/`.before` will not provide the desired behaviour + /// and the systems can run in parallel or in any order determined by the scheduler. + /// Only use `after(GameSystem::B)` and `before(GameSystem::B)` when you know that `B` has already been scheduled for you, + /// e.g. when it was provided by Bevy or a third-party dependency, + /// or you manually scheduled it somewhere else in your app. + /// + /// Another caveat is that if `GameSystem::B` is placed in a different schedule than `GameSystem::A`, + /// any ordering calls between them—whether using `.before`, `.after`, or `.chain`—will be silently ignored. + /// + /// [`configure_sets`]: https://docs.rs/bevy/latest/bevy/app/struct.App.html#method.configure_sets fn after(self, set: impl IntoSystemSet) -> SystemConfigs { self.into_configs().after(set) }