Rename clear_child* to detach_child* (#21470)

# Objective

Fixes #21329 - The naming of the `clear_children` function could be
misunderstood, so we suggest to rename it.

The current `clear_children` function could be understood to despawn the
children, which it does not do. To emphasize the difference between
`clear` and `despawn`, we can rename `clear` to `detach`. So we arrive
at the final naming of `despawn` and `detach`.

## Solution

To improve this, we could rename `clear_children` to `detach_children`
and all other `clear`/`remove` functions too. I also suggest to rename
all `remove_child*` functions for the same reason.

This renaming resulted in a confict because two methods now had the same
name:
- `detach_children(self)`, previously `clear_children`
- `detach_children(self, children: &[Entity])`, previously
`remove_children`

To solve this, I propose we rename the former to `detach_all_children`.
This was chosen because it has the least impact, considering that all
methods do take a slice of children, except this one.

Changing the `insert_*` and `add_*` functions should be discussed. I
think there is less potential for confusion, because they require you to
pass an existing entity. Therefore it should be clear that this does not
spawn anything.

Note: The function `ui_surface.try_remove_children` has not been
renamed.

## Testing

Currently running the tests, but there are unrelated compile errors in
wgpu-hal blocking me (I am on windows).
For this reason, this is a draft pull request. Feel free to provide
feedback already, while I am trying to make the tests run.

## Discussion

As proposed in this PR, this would be a breaking change and will likely
affect a large number of downstream projects directly. If you think this
should be handled differently, via a `#[deprecated]` flag, I can rework
the code to do that.

Is there no documentation to update? The repo yielded no more search
results than this.

---------

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

Author: johannesvollmer

crates/bevy_ecs/src/hierarchy.rs

@@ -277,15 +277,23 @@ impl<'w> EntityWorldMut<'w> {
         self
     }
 
-    /// Adds the given children to this entity
+    /// Adds the given children to this entity.
     /// See also [`add_related`](Self::add_related).
     pub fn add_children(&mut self, children: &[Entity]) -> &mut Self {
         self.add_related::<ChildOf>(children)
     }
 
     /// Removes all the children from this entity.
     /// See also [`clear_related`](Self::clear_related)
+    #[deprecated = "Use detach_all_children() instead"]
     pub fn clear_children(&mut self) -> &mut Self {
+        self.detach_all_children()
+    }
+
+    /// Removes all the parent-child relationships from this entity.
+    /// To despawn the child entities, instead use [`EntityWorldMut::despawn_children`](EntityWorldMut::despawn_children).
+    /// See also [`clear_related`](Self::clear_related)
+    pub fn detach_all_children(&mut self) -> &mut Self {
         self.clear_related::<ChildOf>()
     }
 
@@ -301,19 +309,33 @@ impl<'w> EntityWorldMut<'w> {
         self.insert_related::<ChildOf>(index, &[child])
     }
 
-    /// Adds the given child to this entity
+    /// Adds the given child to this entity.
     /// See also [`add_related`](Self::add_related).
     pub fn add_child(&mut self, child: Entity) -> &mut Self {
         self.add_related::<ChildOf>(&[child])
     }
 
     /// Removes the relationship between this entity and the given entities.
+    #[deprecated = "Use detach_children() instead"]
     pub fn remove_children(&mut self, children: &[Entity]) -> &mut Self {
+        self.detach_children(children)
+    }
+
+    /// Removes the parent-child relationship between this entity and the given entities.
+    /// Does not despawn the children.
+    pub fn detach_children(&mut self, children: &[Entity]) -> &mut Self {
         self.remove_related::<ChildOf>(children)
     }
 
     /// Removes the relationship between this entity and the given entity.
+    #[deprecated = "Use detach_child() instead"]
     pub fn remove_child(&mut self, child: Entity) -> &mut Self {
+        self.detach_child(child)
+    }
+
+    /// Removes the parent-child relationship between this entity and the given entity.
+    /// Does not despawn the child.
+    pub fn detach_child(&mut self, child: Entity) -> &mut Self {
         self.remove_related::<ChildOf>(&[child])
     }
 
@@ -369,14 +391,22 @@ impl<'a> EntityCommands<'a> {
         self
     }
 
-    /// Adds the given children to this entity
+    /// Adds the given children to this entity.
     pub fn add_children(&mut self, children: &[Entity]) -> &mut Self {
         self.add_related::<ChildOf>(children)
     }
 
     /// Removes all the children from this entity.
     /// See also [`clear_related`](Self::clear_related)
+    #[deprecated = "Use detach_all_children() instead"]
     pub fn clear_children(&mut self) -> &mut Self {
+        self.detach_all_children()
+    }
+
+    /// Removes all the parent-child relationships from this entity.
+    /// To despawn the child entities, instead use [`EntityWorldMut::despawn_children`](EntityWorldMut::despawn_children).
+    /// See also [`clear_related`](Self::clear_related)
+    pub fn detach_all_children(&mut self) -> &mut Self {
         self.clear_related::<ChildOf>()
     }
 
@@ -392,18 +422,32 @@ impl<'a> EntityCommands<'a> {
         self.insert_related::<ChildOf>(index, &[child])
     }
 
-    /// Adds the given child to this entity
+    /// Adds the given child to this entity.
     pub fn add_child(&mut self, child: Entity) -> &mut Self {
         self.add_related::<ChildOf>(&[child])
     }
 
     /// Removes the relationship between this entity and the given entities.
+    #[deprecated = "Use detach_children() instead"]
     pub fn remove_children(&mut self, children: &[Entity]) -> &mut Self {
+        self.detach_children(children)
+    }
+
+    /// Removes the parent-child relationship between this entity and the given entities.
+    /// Does not despawn the children.
+    pub fn detach_children(&mut self, children: &[Entity]) -> &mut Self {
         self.remove_related::<ChildOf>(children)
     }
 
     /// Removes the relationship between this entity and the given entity.
+    #[deprecated = "Use detach_child() instead"]
     pub fn remove_child(&mut self, child: Entity) -> &mut Self {
+        self.detach_child(child)
+    }
+
+    /// Removes the parent-child relationship between this entity and the given entity.
+    /// Does not despawn the child.
+    pub fn detach_child(&mut self, child: Entity) -> &mut Self {
         self.remove_related::<ChildOf>(&[child])
     }
 
@@ -731,7 +775,7 @@ mod tests {
     }
 
     #[test]
-    fn remove_children() {
+    fn detach_children() {
         let mut world = World::new();
         let child1 = world.spawn_empty().id();
         let child2 = world.spawn_empty().id();
@@ -740,7 +784,7 @@ mod tests {
 
         let mut root = world.spawn_empty();
         root.add_children(&[child1, child2, child3, child4]);
-        root.remove_children(&[child2, child3]);
+        root.detach_children(&[child2, child3]);
         let root = root.id();
 
         let hierarchy = get_hierarchy(&world, root);
@@ -751,15 +795,15 @@ mod tests {
     }
 
     #[test]
-    fn remove_child() {
+    fn detach_child() {
         let mut world = World::new();
         let child1 = world.spawn_empty().id();
         let child2 = world.spawn_empty().id();
         let child3 = world.spawn_empty().id();
 
         let mut root = world.spawn_empty();
         root.add_children(&[child1, child2, child3]);
-        root.remove_child(child2);
+        root.detach_child(child2);
         let root = root.id();
 
         let hierarchy = get_hierarchy(&world, root);

release-content/migration-guides/rename-clear_children.md

@@ -0,0 +1,16 @@
+---
+title: Renamed `clear_children` methods to `detach_all_children`
+pull_requests: [21470]
+---
+
+In summary, we renamed `clear_*` and `remove_*` methods to `detach_*`.
+This should clarify that these methods do not despawn the child entities.
+
+We renamed several related methods on both `EntityCommands` and `EntityWorldMut`:
+
+- The method `EntityCommands::clear_children` has been renamed to `EntityCommands::detach_all_children`.
+- The method `EntityWorldMut::clear_children` has been renamed to `EntityWorldMut::detach_all_children`.
+- The method `EntityCommands::remove_children` has been renamed to `EntityCommands::detach_children`.
+- The method `EntityWorldMut::remove_children` has been renamed to `EntityWorldMut::detach_children`.
+- The method `EntityCommands::remove_child` has been renamed to `EntityCommands::detach_child`.
+- The method `EntityWorldMut::remove_child` has been renamed to `EntityWorldMut::detach_child`.