One-click promotion of a Stage's current piece of Freight to its downstream

[aayushsrivastava]

Checklist

• I've searched the issue queue to verify this is not a duplicate feature request.
• I've pasted the output of kargo version, if applicable.
• I've pasted logs, if applicable.

Proposed Feature

Allow the user to click one button, which will take the piece of Freight currently in a Stage and promote it downstream.

This capability can be provided in both UI and CLI.

Motivation

This eliminates the need for the user to find the current piece of Freight in a stage and supply that as input when requesting a Promotion. This will greatly improve the user experience when manually promoting what is already in a Stage to its downstream. Especially when the action has to be repeated on multiple DAGs.

From #3193 (comment)

@krancour: We currently make you fiddle with selecting Freight from the timeline because we didn't want to constrain promotion to any given Stage to just whatever was currently in the previous Stage(s). (You might sometimes need to quickly roll prod back to its previous state and you wouldn't want to have to restore test, uat, etc. to that state first in order to get it there.) But there's absolutely no reason we can't have some kind of shortcut for "promote what's here now" downstream. I think the only challenge standing in the way of that is, again UX. We'd need to find a way to very clearly and visually differentiate between the two actions of "promote something to my downstreams" vs "promote what I have now to my downstream."

Suggested Implementation

It could be a purely cosmetic change which uses existing APIs, but it would perhaps be better to introduce new API to implement this feature server-side.

[krancour]

I think something else you'd proposed in #3193 is that one click "push downstream" would only be available for Stages that have only one Freight request.

It could be a purely cosmetic change which uses existing APIs, but it would perhaps be better to introduce new API to implement this feature server-side.

The existing "Promote to Stage" and "Promote to Downstream" endpoints both take just three arguments: Project name, Stage Name, Freight name. So the existing endpoints should handle this just fine without a single change. Your proposed feature would just be a shortcut to filling in the Freight name argument.

cc @jessesuen to get impressions on the value of such a feature.

cc @Marvin9 to think about what UI for something like this might look like. It would be very important to distinguish between "select Freight to promote downstream" vs "promote the Freight the Stage currently has to downstream."

[Marvin9]

My quick instinct says some action item on the right side of current freight in the node would work.

[krancour]

@Marvin9 don't we already put something there on the right (only if the Stage has multiple downstreams, iirc)? That existing action is the thing I want to avoid confusion with.

[Marvin9]

Right @krancour that is truck icon on the edge of node.. this will be right besides the freight text that user wants to promote in one click.. it'd be as self-explanatory as possible

[krancour]

Thanks for clarifying @Marvin9!

[aayushsrivastava]

I think something else you'd proposed in #3193 is that one click "push downstream" would only be available for Stages that have only one Freight request.

Yeah, when creating this issue I was not sure if we wanted to design this in a general manner for all types of Stages or limit it to Stages with only one Freight.

But I guess @Marvin9's suggestion of putting it beside the Freight text makes it unambiguous and still solves it in a general manner.

I'll update the title and initial post to reflect that it's only one Freight request.

[krancour]

I guess @Marvin9's suggestion of putting it beside the Freight text makes it unambiguous

I'll update the title and initial post to reflect that it's only one Freight request.

I think the stages will show multiple freight if they have them, so if there's a one-click "promote downstream" button next to each, then I think we don't have to limit it to Stages that request Freight from only one source.

There's our general solution.