term: simplify multiple mentions about dvc.yaml + dvc.lock + .dvc files

[jorgeorpinel]

UPDATE: One thing left here, see #1663 (comment) below.

Continues #1431

Extracted from #1384 (review) et al.

To achieve this, we will probably need to introduce a new glossary term such as "Special DVC files".

[shcheklein]

Not sure about Special though. They are not very special I guess.

[jorgeorpinel]

"DVC metafiles"? "DVC-specific files"? Can't use just "DVC files" because it looks almost like ".dvc files".

[shcheklein]

DVC files with if needed sounds good to me. I don't how to generalize it better. .dvc, dvc.lock, dvc.yaml - they all DVC files, right?

[jorgeorpinel]

People have always called .dvc files "DVC files", which makes sense and it's one of the reasons we wanted to stop using the term "stage file" (even before 1.0) because we really had to force it and still was not adopted. Throwing in dvc.yaml (and dvc.lock) sounds like making a similar mistake, where we'll have to force people to get that DVC files are not just .dvc files but also other files.

Also, technically theres plenty other "DVC files" such as .dvc/config or plots templates, but we wouldn't include those in the term.

Maybe "stage file" wasn't such a bad term after all...

[jorgeorpinel]

OK, so I vote for "DVC metafiles" (would mostly be used in plural). WDYT @shcheklein? Should we call in a vote from everyone via Slack or mentioning them here perhaps?

[jorgeorpinel]

Actually... a term to group the files may not solve our problems. We also have to repeat the phrase "stages and .dvc files" a lot, and that could not be replaced by a term that refers to files.

We may need a broader concept, kind of like how we used to consider .dvc files "(orphan) stages" before, except I would use that term anymore since it would be overloaded... So maybe "DVC nodes", "DVC blocks"? Idk.

This could be in addition to "DVC (meta)files"

• DVC node: it can have deps and outs (a possible link in a DAG chain). Includes stages (found in dvc.yaml) and the data structure in .dvc files (the latter has no command thus doesn't represent a process, thus is not a stage).
• DVC metafile: dvc.yaml files (and corresponding dvc.lock files) and .dvc files. This term refers to special YAML schemas used in DVC.

Although TBH the true solution for all this confusion, I think would start with iterative/dvc#4278.

[shcheklein]

We may need a broader concept, kind of like how we used to consider .dvc files "(orphan) stages" before, except I would use that term anymore since it would be overloaded... So maybe "DVC nodes", "DVC blocks"? Idk.

sounds too complicated,

We also have to repeat the phrase "stages and .dvc files" a lot, and that could not be replaced by a term that refers to files.

you mean targets? it's mix of everything - path, .dvc. stage names, etc. I guess there is no way to avoid this and it's fine. Also, I would check how other tools solve this.

OK, so I vote for "DVC metafiles"

DVC metafiles is fine.

Should we call in a vote from everyone via Slack or mentioning them here perhaps?

I hope we don't need everyone to vote on this.

[jorgeorpinel]

OK. I'm just concerned that the terminology in the core repo will be very different. Terms like DVC-file and stage file are probably still around and even output to users as help messages/ warnings, etc.

[jorgeorpinel]

UPDATE on this: we actually went for "DVC Files", already started implementing in #2043 (deployed to https://dvc.org/doc/user-guide/dvc-files).

[jorgeorpinel]

• And after 2.0 docs #2026 is merged, the only thing left (if worth it) will be to decide which instances of longer phrases like "dvc.yaml and .dvc file" to replace for just "DVC Files", and possibly vice versa (be specific in instances of the latter that should for some readon list both or mention only one of the file types).

[iesahin]

I'll check this after the merge of #2026.

[jorgeorpinel]

Closing as probably done (from the comments above). @iesahin feel free to double check if you didn't though. Thanks