Rename SortedRenderPhase add to add_retained

[kristoff3r]

Objective

In #22966 the semantics of the add method on SortedRenderPhase was changed from the items being cleared at the end of the frame, to items being retained until they are removed. A new add_transient method was added with the old functionality, but this is a big migration hazard because it's a major semantic change that doesn't give any compiler errors or warnings.

I discovered this after updating bevy_vector_shapes to the RC and seeing drawings not being cleared properly.

Solution

Rename add to add_retained both for clarity and to make old uses not compile, so the affected users will know to look in the migration guide.

A sentence about this should be added to the migration guide if/when this is backported to the 0.19 release branch.

Testing

It compiles (hopefully).

[eswartz]

The rationale for the renaming and forcing users to accommodate the change makes sense to me. I think it warrants an explanatory note in the docs, though.

[eswartz]

Perhaps add a comment here to explain what "retained" means, vs. add_transient?

[kristoff3r]

For this data structure specifically it doesn't mean much except that the item is not automatically removed. I don't know enough about the change list machinery to give a succinct explanation here, and in principle you could use it in other ways as well.

I guess I could add a "Unlike add_transient, the item is not removed by the end of the frame and needs to be updated by an external system"?

[eswartz]

I guess I could add a "Unlike add_transient, the item is not removed by the end of the frame and needs to be updated by an external system"?

Right, though I just meant the bare minimum to explain what "retained" means :). Wording it positively, it could be Adds a [PhaseItem] to this render phase, which will persist between frames until removed.

Then the add_transient doc -- which I see is a bit odd to read, could also be reworded to Adds a [PhaseItem] to this render phase, which will be removed automatically after this frame.