stage: Rename some commands as stage subcommands.

[iesahin]

I'm sure this idea has mentioned in several different places but I couldn't find an issue that collects all stage related commands under dvc stage

The following commands may be renamed:

• ˋdvc freezeˋ to dvc stage freeze
• dvc unfreeze to dvc stage unfreeze
• dvc remove can be split into dvc stage remove and dvc data remove
• dvc dag to dvc stage dag or dvc stage graph
• dvc repro to dvc stage repro or dvc stage run

The current ones can be deprecated for the next major release (3.0), and removed in the following major release (4.0).

Might be related to #7093

[skshetry]

To be honest, I haven't been a fan of subcommands, as it takes too much effort to type. Reading through https://clig.dev/#subcommands, it does seem to encourage subcommands for complex software (which is not very clear here):

If you’ve got a tool that’s sufficiently complex, you can reduce its complexity by making a set of subcommands. If you have several tools that are very closely related, you can make them easier to use and discover by combining them into a single command (for example, RCS vs. Git).

They’re useful for sharing stuff—global flags, help text, configuration, storage mechanisms.

[daavoo]

I think it makes sense to split commands that can be currently used for different things (dvc remove can be split into dvc stage remove and dvc data remove).

For others where there is a single purpose (i.e. dvc freeze / dvc unfreeze) I have no strong opinion about moving to subcommand or not.

dvc dag to dvc stage dag or dvc stage graph

This one doesn't make much sense to me.

[iesahin]

To be honest, I haven't been a fan of subcommands, as it takes too much effort to type. Reading through https://clig.dev/#subcommands, it does seem to encourage subcommands for complex software (which is not very clear here):

To reduce typing, there is an alias facility in every shell. One can define a dsa alias for dvc stage add.

These commands are infrequent commands. In these cases, remembering / looking up the command becomes more important than to type.

Actually I'm also not a big fan of subcommands but we have an irregular interface: We have stage add and stage list, two most frequently used stage commands as subcommands, but the other half of the stage related commands are not stage commands. If this irregularity could be solved the other way, by dropping stage from stage add and stage list, that's better but I think it's not possible at this point.

[iesahin]

dvc dag to dvc stage dag or dvc stage graph

This one doesn't make much sense to me.

dvc dag command is similar to dvc stage list, showing the DAG of stages. It could even be called dvc stage list --dag

[daavoo]

dvc dag command is similar to dvc stage list, showing the DAG of stages. It could even be called dvc stage list --dag

I understand now.

Could dvc stage list --dag be something likedvc stage show?

[iesahin]

Could dvc stage list --dag be something likedvc stage show?

Yes, it could be dvc stage show, but I think emphasizing "graph" or "dag" in the name is more clear.

[omesser]

@dberenbaum

ping about this 🔔 😄

Regardless¹ of 3.0 release - where does this stand?
Is it under discussion / disagreement?
this proposal sounds very correct to me. Avoiding subcommands doesn't make things better or easier if you have too many top level commands or if you can't find stage operations under dvc stage where it makes sense to look for them

Footnotes

1. or not? depends on state of disagreement I guess ↩

[dberenbaum]

While I like the idea and feel the same pain that the CLI feels disorganized, and the proposal makes sense from a logical perspective, I see it as primarily an internal pain. Other than the dvc repro vs dvc exp run discussion, I have yet to see users confused or pained by these top-level commands (please add them here if you come across them). This also goes against our efforts to try to avoid breaking changes for users -- many will have to change their scripts to use the reorganized commands. I also think this is not something we have capacity to decide this late for 3.0 -- it's likely to generate lots of different opinions.

Let's not tie it to 3.0, but why don't we start introducing aliases in the subcommands if this is the direction we want to go, and we can worry about dropping the top-level commands later?

[omesser]

Thanks @dberenbaum

Let's not tie it to 3.0, but why don't we start introducing aliases in the subcommands if this is the direction we want to go, and we can worry about dropping the top-level commands later?

Yes, no specific need to tie to 3.0 or urgency, but I hope we won't actually wait for user to yell about such things. if we agree that some experiences are better, or some structure makes sense... we need to make it easier to learn, not just easier to retain your knowledge if you're already a user.

This also goes against our efforts to try to avoid breaking changes for users

soft deprecation + aliases 😄

[dberenbaum]

@omesser Maybe a first step should even to be do a very rough docs draft (not bothering with updating all old links etc.) to see how it simplifies things and whether it feels impactful enough to prioritize.

[dberenbaum]

Very minor suggestion would be to add a stages alias since a lot of these subcommands are not about a single stage.