ref: document dvc queue

[pmrowla]

Initial command reference changes for dvc queue and dvc exp
Related to #3658

TODO:

• dvc exp run changes/deprecations
• dvc queue examples

[dberenbaum]

@pmrowla Is this ready for review?

[pmrowla]

@pmrowla Is this ready for review?

Everything that's pushed can be reviewed, but it still needs examples and the exp run changes

[daavoo]

Should we also include this kind of warning in core DVC (i.e. actually logging DeprecationWarning)?

[pmrowla]

Eventually yes, but there haven't been any formal decisions about what and what not to deprecate w/the queueing changes. I think the current plan is to not rush formally deprecating the existing experiments UI since the dvc queue workflow will probably change once we get some user feedback

[dberenbaum]

It's fine to say that this will be deprecated (we are already doing it here). There shouldn't be a hard requirement to include deprecation of experiment features since they are "experimental" in 2.X, but it would be nice.

[pmrowla]

@dberenbaum @jorgeorpinel this is ready for review.

I've added examples for queue logs and queue status, not sure how detailed we want to get w/the other commands given that we didn't have many examples for queueing at all in the first place.

[pmrowla]

@dberenbaum I can go ahead and continue making all of the suggested copy-edit type changes, but I was under the impression that this PR was going to be merged as-is and then further changes would be taken over by the docs team (and that these review issues were notes @jorgeorpinel was making for future reference)

see: #3715 (comment)

[dberenbaum]

Okay, nothing blocking, so I'll merge as is. I hadn't seen any responses to some of the comments so wasn't sure what was happening.

[shcheklein]

Product question - do we actually plan to deprecate anything related to "queued experiments" in the dvc exp run and other dvc exp commands? To me it still feels a bit weird (and too low level) that we have to expose dvc queue to also manage experiments. Ideally one interface should be more or less enough (and dvc queue is needed to do more granular, sophisticated tasks).

[dberenbaum]

do we actually plan to deprecate anything related to "queued experiments" in the dvc exp run and other dvc exp commands?

The deprecations in here are for --run-all and -j. I wavered on this but I still leaned towards deprecating those.

My rationale:

• --run-all is not the most helpful way to start the queue because it runs in the foreground. I think by default we should suggest to start the queue in the background. We could hint to use dvc queue start when an experiment is queued.
• --run-all and -j are awkward in dvc exp run because they are detached from the typical behavior of dvc exp run and are mutually exclusive from the other options.
• Although the queue commands should generally be low level, I think dvc queue start is more straightforward than dvc exp run --run-all and provides a general intro to the queue commands in case they are needed later.

[shcheklein]

@dberenbaum makes total sense. We can still probably expose queue to the experiments level in a different way? e.g. dvc exp run-all ? etc