Add a doc note about despawn footgun

[benfrankel]

Objective

The Despawn command breaks the hierarchy whenever you use it if the despawned entity has a parent or any children. This is a serious footgun because the Despawn command has the shortest name, the behavior is unexpected and not likely to be what you want, and the crash that it causes can be very difficult to track down.

Solution

Until this can be fixed by relations, add a note mentioning the footgun in the documentation.

[Nilirad]

I'm not in favor of adding notes about other crates that are not dependencies. I would avoid being too specific and instead just note that despawning an entity won't have side effects on other entities (until we have relations).

If a user knows how to use add_child/push_children/etc, they should also know how to use despawn_recursive since they are both contained in the same plugin. Therefore I suggest to add specific references to despawn_recursive in those methods instead and keep it very general on bevy_ecs.

EDIT: Further thoughts: IMO despawn could be renamed to despawn_single, and despawn_recursive to despawn (maybe not both in the same release to avoid migration hell)

[benfrankel]

I'm not in favor of adding notes about other crates that are not dependencies. I would avoid being too specific and instead just note that despawning an entity won't have side effects on other entities (until we have relations).

If a user knows how to use add_child/push_children/etc, they should also know how to use despawn_recursive since they are both contained in the same plugin. Therefore I suggest to add specific references to despawn_recursive in those methods instead and keep it very general on bevy_ecs.

EDIT: Further thoughts: IMO despawn could be renamed to despawn_single, and despawn_recursive to despawn (maybe not both in the same release to avoid migration hell)

Makes sense. Renaming things can be in a different PR. I updated the notes to remove specific references to items in bevy_hierarchy, but still mentioning bevy_hierarchy itself as an example of what can go wrong.

[Nilirad]

LGTM.

Do you want to document despawn_recursive in children addition methods in bevy_hierarchy on this PR, or do you want to leave it as future work?

[benfrankel]

LGTM.

Do you want to document despawn_recursive in children addition methods in bevy_hierarchy on this PR, or do you want to leave it as future work?

I'll leave it as future work.

[Nilirad]

I furtherly addressed the despawn footgun in the bevy_hierarchy crate: #10951