Rename Add to Queue for methods with deferred semantics

[BenjaminBrienen]

Objective

• Fixes Rename EntityCommands::add to EntityCommands::queue #15106

Solution

• Trivial refactor to rename the method. The duplicate method push was removed as well. This will simpify the API and make the semantics more clear. Add implies that the action happens immediately, whereas in reality, the command is queued to be run eventually.
• ChildBuilder::add_command has similarly been renamed to queue_command.

Testing

Unit tests should suffice for this simple refactor.

---

Migration Guide

• Commands::add and Commands::push have been replaced with Commnads::queue.
• ChildBuilder::add_command has been renamed to ChildBuilder::queue_command.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[alice-i-cecile]

Can you replace https://docs.rs/bevy/latest/bevy/hierarchy/struct.ChildBuilder.html#method.add_command as part of this PR?

[BenjaminBrienen]

Can you replace https://docs.rs/bevy/latest/bevy/hierarchy/struct.ChildBuilder.html#method.add_command as part of this PR?

I've already renamed it to enqueue_command. I guess I should mention that in the description as well! Let me know if I've misunderstood you and indeed forgot a refactor.

[alice-i-cecile]

Aha, I missed it! I've updated the migration guide in your PR.

[NthTensor]

Surprised this isn't a larger change. I like this much better.

Do we want to do the same with EntityCommands?

[alice-i-cecile]

Do we want to do the same with EntityCommands?

Yes please!

[BenjaminBrienen]

So instead of insert_reflect we have enqueue_reflect? All the ones that wrap around commands.enqueue, I assume.
If so, then we'd also be renaming InsertReflectWithRegistry.

[janhohenheim]

Happy to see this resolved so quickly, thanks :)

[NiseVoid]

So instead of insert_reflect we have enqueue_reflect? All the ones that wrap around commands.enqueue, I assume. If so, then we'd also be renaming InsertReflectWithRegistry.

I think @NthTensor was referring to EntityCommands::add

[janhohenheim]

@BenjaminBrienen yeah, looks like you missed this one. The reflect stuff doesn't need to be touched :)

[alice-i-cecile]

So instead of insert_reflect we have enqueue_reflect? All the ones that wrap around commands.enqueue, I assume. If so, then we'd also be renaming InsertReflectWithRegistry.

insert_reflect is different: it adds a new component. The APIs we want to change are just those that are adding new commands directly. This semantic similarity between add and insert is a huge part of why we want this change in the first place!

[BenjaminBrienen]

@BenjaminBrienen yeah, looks like you missed this one. The reflect stuff doesn't need to be touched :)

Weird. This file seems to escape VSCode's search feature. fn add doesn't show the file for me. Fixing now!

[alice-i-cecile]

Looks like a couple were missed in doc tests: https://github.com/bevyengine/bevy/actions/runs/10873672267/job/30170042797?pr=15234#step:5:1101

[iiYese]

Is there something better than enqueue? Cause if you do .enqueue(A) and then .enqueue(B) but A has the side effect of enqueueing C the effect order is A, C, B not A, B, C.

[alice-i-cecile]

Is there something better than enqueue? Cause if you do .enqueue(A) and then .enqueue(B) but A has the side effect of enqueueing C the effect order is A, C, B not A, B, C.

I like queue better but I'm pretty sure I'm outvoted :p Doesn't solve the problem raised there though. IMO this is a very weird edge case: worth mentioning in the docs but not worth using a less clear name.

[Shatur]

I personally liked "push" 😅
But I also prefer "queue" to "enqueue".

[janhohenheim]

Big queue fan here, but also not a native speaker

[alice-i-cecile]

@BenjaminBrienen can you please swap all uses of enqueue to queue? I've heard enough!

[BenjaminBrienen]

@BenjaminBrienen can you please swap all uses of enqueue to queue? I've heard enough!

Should I leave this "enqueue" alone?
https://github.com/bevyengine/bevy/blob/main/crates/bevy_render/src/renderer/mod.rs#L152

There are a few more examples of "enqueue" in doc comments.

[alice-i-cecile]

Yep, leave the rendering stuff alone for this PR. I'm also fine to leave the docs alone.

[alice-i-cecile]

Awesome. If you have a chance, please update the PR title and description to match. Otherwise I'll do it on merging tomorrow during my weekly merge train.

[alice-i-cecile]

@BenjaminBrienen doc links are broken due to the rename (scroll down the CI run...) and there's a simple merge conflict. Ping me when you've gotten to that and I'll merge it in.

[BenjaminBrienen]

@alice-i-cecile should be fixed now, just waiting on the CI :)

[BenjaminBrienen]

now it should be good... ?