run: deprecate in favor of stage add

[jorgeorpinel]

What's the roadmap for phasing out dvc run? Is there another issue tracking this? Thanks

On the docs side, beyond just removing https://dvc.org/doc/command-reference/run, we'd need to review all the example code blocks using run... (iterative/dvc.org/issues/2076)

[dberenbaum]

Are we even certain we want to do this? It seems like it's still useful as a shortcut for dvc stage add && dvc repro (or exp run instead of repo).

[shcheklein]

My 2cs on this - for me run was a bit confusing because of this double semantics (create + actually run). And we have a few discussions about changing this long long time ago. My personal preference would be to have dvc stage add and add an option dvc stage add --run, for example if we need to actually execute it.

Btw, I think it's a shortcut for dvc stage add && dvc repro dvc.yaml:stage-name?

[jorgeorpinel]

it's a shortcut for dvc stage add && dvc repro dvc.yaml:stage-name
add an option dvc stage add --run

Agree with Ivan on the UI if we're keeping this shortcut 🙂

[karajan1001]

dvc run equals to dvc stage add plus dvc repro. But in :

dvc/dvc/stage/__init__.py

Lines 389 to 407 in 353e4cf

	def reproduce(self, interactive=False, **kwargs):
	if not (kwargs.get("force", False) or self.changed()):
	if not isinstance(self, PipelineStage) and self.is_data_source:
	logger.info("'%s' didn't change, skipping", self.addressing)
	else:
	logger.info(
	"Stage '%s' didn't change, skipping", self.addressing
	)
	return None
	msg = (
	"Going to reproduce {stage}. "
	"Are you sure you want to continue?".format(stage=self)
	)
	if interactive and not prompt.confirm(msg):
	raise DvcException("reproduction aborted by the user")
	self.run(**kwargs)

stage.reproduce called stage.run. Maybe we should rename them?

[efiop]

@karajan1001 More precisely dvc stage add is dvc run --no-exec. dvc repro will also walk the dependencies and reproduce them, so it is not quite the same.

@jorgeorpinel Regarding the roadmap. We've introduced stage add for experiments, as run was odd for that and intended to keep dvc run/repro for now, to see if we still need them in particular scenarios or if experiments will actually replace them both together. For now it is not clear, but we will get back to it in the future.

Closing for now, since there are no action points here. Feel free to transfer into discussions if there is something left to discuss.

[shcheklein]

So, what do we recommend by default? run or stage add?

[efiop]

@shcheklein For old scenarios without experiments - run, for experiments or when you would otherwise use --no-exec - stage add.

[shcheklein]

Hmm, so, what should we use in the Get started, for example? When we build the pipeline we don't have experiments yet, but we'll have them in the very last section. Keep using dvc run? But then to be honest it's not clear where we want to use the dvc stage add at all? I would prefer to have a single default in the docs and mention the second command only if we have a very clear case for it (and don't see one for now). It will be very confusing to explain two different (but very similar) commands in docs when we have different things related to the pipelines.

@jorgeorpinel I think in docs we can discuss with @dberenbaum and default to one of those and mention in the second that this is a short cut pretty much. If we decide to keep both in DVC, let's use dvc run then for now (and mention --no-exec option when it makes sense) and in the dvc stage add just redirect to dvc run. My take - It'll be the least confusing thing for users.

WDYT?

[jorgeorpinel]

Since we have #5846 now its prob best to wait before updating docs, and stage add would be the main one, I think (the run ref. redirecting there).

[karajan1001]

dvc run is shortcut for dvc stage add && dvc stage repro, just like git pull and git fetch && git merge.
But git pull is a highly frequent command, while dvc run only used once at the beginning.

[shcheklein]

thanks @karajan1001

while dvc run only used once at the beginning.

so, means that we should get rid of it in your opinion? (no need for a short cut for a rarely used combination). Also, I think we can easily add a flag (dvc stage add --run) if we'll see that it's needed.

[shcheklein]

To add more to this:

@casperdcl mentioned during the meeting that we have this in the "official" blog pos:

Note, we use dvc stage add command instead of dvc run. Starting from DVC 2.0 we begin extracting all stage specific functionality under dvc stage umbrella. dvc run is still working, but will be deprecated in the following major DVC version (most likely in 3.0).

It means that (at least from the docs perspective) it makes sense to get rid of dvc run everywhere, replace with dvc stage add - it'll be simpler and consistent.

(Same btw, applies to the dvc repro - in many case it might make sense to start replacing this with dvc exp run)

[jorgeorpinel]

btw, applies to the dvc repro - in many case it might make sense to start replacing this with dvc exp run

Probably but will everything be an experiment then? Not sure, sounds like a separate discussion.

[casperdcl]

yes and as also mentioned... is dvc run && dvc repro identical to dvc stage add && dvc exp run && dvc exp gc?

[jorgeorpinel]

Note that run is not exactly stage add + repro. Explanation in #5846 (comment)

[casperdcl]

I don't mean an equivalent of just run. I mean an equivalent of run && repro.

I think it is extremely important to work out if it is identical to stage add && exp run && exp gc.

For example, I presume:

• the combination of stage add && exp run will encompass the validation checks of the deprecated run command
• exp run && exp gc is equivalent to the deprecated repro command

[jorgeorpinel]

Your presumptions seem correct (would need to double check). But I don't get the run && repro workflow.

[casperdcl]

well (off topic but...) run + modify/clear cache/pull on another machine + repro was a standard use case right?

[jorgeorpinel]

Ah gotcha. The && made it seem like we were running them in tandem on the same machine. Yes you run once, repro later/ from elsewhere.

[dberenbaum]

I think it's fine to move towards this, but it seems like there are a few dependencies that need to be addressed first:

• stage add: fails with dirs that will be created later by the cmd(s) #5802
• QA for any other possible regressions
• dvc stage add --run option

[jorgeorpinel]

QA for any other possible regressions

Well, the change will break backward compatibility once we deprecate run (in 3.0?) anyway, right? Just because of the different command name. Unless we turn run into an alias of stage add --run (is that the plan?)
UPDATE: Asked in #5846 (comment)

[dberenbaum]

I don't think the goal should be to have run and stage add --run be identical but to understand the differences as much as possible. #5802 seems like it's probably worth changing behavior in stage add, but the difference mentioned in #5846 (comment) is okay to document. If we don't at least try to do that and we recommend users switch to stage add --run, users will be frustrated if their workflows break, right?

[jorgeorpinel]

Agree. I guess I'm not sure what regressions you're suggesting to test for, if we know this will be a breaking change (run will go away or become an alias of stage add --run).

[dberenbaum]

I meant to QA for any differences between run and stage add --run. Does that clarify? Maybe I just shouldn't have said "regressions"?

[shcheklein]

For the record - one more question about this on Discord: https://discord.com/channels/485586884165107732/563406153334128681/840270790712229889

What are the reasons behind introducing dvc stage add will be dvc run deprecated? The only difference I can see is that dvc stage add has no option to execute stages if I understand it correctly.

[ktagowski]

So I asked this question as I noticed dvc stage add in the docs. And It was confusing for me, as the current documentation for dvc run and dvc stage add is almost the same. From the user's point of view, I would stick to one function and deprecate the other.

[talosiot-will]

Would it be useful behavior to run the experiment, then permanently alter the dvc.yaml file if and only if the command runs successfully?

[talosiot-will]

I should have been more clear. If dvc run is a shortcut for dvc stage add && dvc stage repro then the the dvc stage add command goes first and alters my dvc.yaml file "permanently" (which was a poor word choice). Then after the dvc.yaml file has my changes will the experiment run with dvc stage repro. By then, if the experiment fails to run, my dvc.yaml file already has the (bad) changes in it.

A workflow that I've found useful is to interrogate the source code and params file, then change the dvc.yaml file only at the end after I know for a fact my experiment runs. https://github.com/talosiot-will/dvcrecord

[jorgeorpinel]

Right. I guess it's not *exactly* dvc stage add && dvc stage repro (BTW sage repro is hypothetical here) for that (and maybe other) reasons. Cc @karajan1001 (per #5819 (comment))

interrogate the source code and params file, then change the dvc.yaml file only at the end

Are you suggesting stage add runs the command internally just to see if it won't fail? That would prob defeat the point of separating the stage definition from the stage execution (stage add / exp run).

[talosiot-will]

Understood that the separation of stage definition from execution is important, particularly for very long running stages. That should certainly still be possible. I think all I'm suggesting is that there are times when the dev loop of stage add, then stage repro, then debug and troubleshoot, then back to stage add can be streamlined a bit by just removing the need stage add on its own.

[jorgeorpinel]

Agree. I think that's what the proposed stage add --run aims to provide 🙂 (if/when run goes away).

[dberenbaum]

@talosiot-will dvcrecord looks nice! I saw you post it in Discord but didn't have a chance to check it out until now. Feel free to post elsewhere, like in https://github.com/iterative/dvc/discussions/categories/show-and-tell. There have been a few issues and discussions more generally about creating a Python API for generating the DVC DAG to avoid repetition and create more flexibility, but we haven't really agreed on a structure or prioritized it at this point. Feel free to chime in to discussions like #5646 if you're interested.

[ktagowski]

Also, if dvc run will be removed, I think that dvc remove should be renamed to dvc stage remove to keep a straightforward syntax.

[jorgeorpinel]

Agree. See #5791

[ktagowski]

Seems great