term: don't use "DVC-file" or "stage file" anymore, use ".dvc file"

[jorgeorpinel]

To match iterative/dvc.org/issues/1366 — which does not include updating any dvc command example output.

Let's update all user output strings please, and hopefully debug output too. And then open a docs PR to reflect any of these changes, as usual.

[DiPaolo]

I would like to start working on the issue.

@jorgeorpinel could you please clarify what's the difference between the term 'DVC-file' (according to #1366) used for dvc add/import/import-url and the term '.dvc file' used in all other cases?

[jorgeorpinel]

Hi @DiPaolo OK sure, thanks! TBH some or most of this may already be applied but it would be great to double check all the instances.

• "DVC-file" and "stage file" were the official ways we used to refer to .dvc files. Neither term should exit any more in docs (except in old blog posts, that's OK).
• "DVC file" (no hyphen) can be any file DVC uses to track stuff, i.e. this: https://dvc.org/doc/user-guide/dvc-files (dvc.yaml, dvc.lock, and .dvc files, basically but maybe at some point we will throw params files or other formats in there too).

[DiPaolo]

@jorgeorpinel thanks! It becomes much more clear now.

One more question: I discovered the documentation on dvc.org widely operates with the term ".dvc file(s)", whereas you mentioned "DVC file" in your recent reply. What should I use while replacing outdated "DVC-file" and "stage file"?

[jorgeorpinel]

Wait I was confused @DiPaolo. I see this is a core repo issue. I was thinking about docs, where iterative/dvc.org/issues/1366 is already done.

So yes, these terms are probably still pervasive in this repo. Reviewing and updating them would be ideal but keep in mind only the user-facing messages (e.g. logger.info/warn) are really important. Debug output would also be nice to update if it's manageable. Docstrings, function names I would first make a list and confirm with @efiop, thanks.

dvc.org widely operates with the term ".dvc file(s)", whereas you mentioned "DVC file" in your recent reply

.dvc files are one kind of DVC files. See https://dvc.org/doc/user-guide/dvc-files, and the discussion in iterative/dvc.org/issues/1663 (feel free to participate there).

What should I use while replacing outdated "DVC-file" and "stage file"?

Depends on the context. If it specifically refers to .dvc files (e.g. in dvc add/import then ".dvc file", if it's specifically about dvc.yaml (e.g. dvc run) then that. If it's either one (e.g. with dvc repro) or if not sure, then "DVC file" is the safer bet.

But if you find the terminology confusing I'm not sure you should jump into this issue yet.