Story: Add language support for DVC.yaml

[shcheklein]

We need to help users manage stages, metrics, models, params within the editor.

[jorgeorpinel]

We already have the basic support to check it again the schema

But via the YAML extension by RedHat right? If so should it be recommended somewhere in the Get Started page?

[mattseddon]

We have an in-product prompt to install that extension. It was added in #903. Under this ticket we'll look at expanding support outside of the scope of that extension 👍🏻.

[jorgeorpinel]

Oh, I did notice that box but I thought it was an automatic VSC prompt. Cool then

[wolmir]

Updates:

• Highlighting is working, but we'll need to adjust colors, so we can leave it for later.

Language support:

• (Easy) We can link the file/folder references in the dvc yaml files so VSCode can open them in a new tab.
• (Medium) We can register the parameters as symbols, so the user can jump to them on a Cmd+Click on their reference.
• (Medium) We can register the metric fields as symbols for the same reasons.
• (Hard, because of scoping issues) We can provide definitions for the symbols referenced in the variables, for the same reasons.

I'm posting this now because I believe I have a shot at a first iteration of the first three items in the language support list, and I would like to post a demo tomorrow.

[shcheklein]

@wolmir can you share some video (even WPI is totally fine)

We can link the file/folder references in the dvc yaml files so VSCode can open them in a new tab.

Can we do things like:

• I edit it in one place and it's being updated in all other places?
• I want to highlight the file in the navigator?

We can register the parameters as symbols, so the user can jump to them on a Cmd+Click on their reference.

• Can we show the value?

Hard, because of scoping issues

Could you clarify please?

@skshetry @dberenbaum anything from the top of your head that would simplify editing /managing DVC files?

[wolmir]

@shcheklein I'll try to record a video today

I edit it in one place and it's being updated in all other places?

Technically yes, but can you give me a specific example, please?

I want to highlight the file in the navigator?

Yes that's possible, but we have to be careful with the highlight color to not conflict with other extensions like GitLens for example.

Can we show the value?

Yes, traditionally as a hover tooltip, but there are other possibilities like a faded text next to the symbol.

Could you clarify please?

From the DVC docs, the variables are scoped per stage/foreach block and can't be referenced outside of it.
They can also be shadowed by using the same variable name in an inner scope.

[skshetry]

From the DVC docs, the variables are scoped per stage/foreach block and can't be referenced outside of it. They can also be shadowed by using the same variable name in an inner scope.

@wolmir, I think you can ignore the inner scope unless someone asks for it (it's an arcane feature).

That said, I think it'd be easier to design it in a way that resolves each stage independently, considering the support for for-each, as the extension still needs to understand item/key (which is shadowed).

[wolmir]

Thanks @skshetry !

While you're here, can you think of other ways VSCode can help with dvc.yaml?

[skshetry]

While you're here, can you think of other ways VSCode can help with dvc.yaml?

I think a view of all stages in the sidebar would be nice which takes you to the individual definitions of the stages and maybe allows running each individually (just like the tests).

I don't know if it's in the scope of this ticket, but we could also have linter-like features, eg: parameter does not exist or is out of sync, etc.

[dberenbaum]

👍 to pretty much everything here.

---

We have an in-product prompt to install that extension. It was added in #903. Under this ticket we'll look at expanding support outside of the scope of that extension 👍🏻.

Can we call this out even more? Like @jorgeorpinel, I didn't realize it was for DVC and ignored it.

---

• (Medium) We can register the parameters as symbols, so the user can jump to them on a Cmd+Click on their reference.

This would be nice. Even better would be to suggest individual parameters in IntelliSense by parsing params.yaml (or a custom params file if the key has been provided).

• (Medium) We can register the metric fields as symbols for the same reasons.

Unlike params, there shouldn't be individual metrics fields in dvc.yaml. All metrics values should be path-level references. Maybe I'm misunderstanding this point.

• (Hard, because of scoping issues) We can provide definitions for the symbols referenced in the variables, for the same reasons.

Not sure I follow what this would do.

---

I think a view of all stages in the sidebar would be nice which takes you to the individual definitions of the stages and maybe allows running each individually (just like the tests).

In addition, it would be nice if we could show in which other stages a path is referenced and in what context (what is the stage name and is the path a dep/out/etc.).

---

Other ideas that I think would be helpful (apologize if some are wildly unrealistic, but I'm excited for this as it could greatly improve the experience of creating pipelines):

Snippets

Suggest filled-out templates for sections of dvc.yaml:

• Whole stages, or maybe have different stage templates (like dvc exp init --type).
• A basic plot template or different templates for various plot types (examples in https://dvc.org/doc/dvclive/api-reference/live/log_plot?tab=roc#supported-plots, https://dvc.org/doc/command-reference/plots#example-smooth-plot).
• Foreach stage template.
• Vars template.

IntelliSense Suggestions

• Suggest path values under sections like wdir, deps, outs, params, metrics, and plots. Even better would be to use file extensions to only suggest appropriate paths (for example, metrics support JSON/TOML/YAML).
• Suggest params values from params.yaml. If a specific parameters file is specified, suggest values from that file.
• When using vars or foreach and ${} syntax, suggest valid values based on vars/foreach items (and ideally put these at the top of suggestions).

[wolmir]

Nice, thanks @dberenbaum !

[wolmir]

WIP stuff:

Screen.Recording.2022-07-29.at.16.14.13.mov

Screen.Recording.2022-07-29.at.16.16.44.mov

Screen.Recording.2022-07-29.at.16.41.24.mov

[mattseddon]

@shcheklein ticket needs a checklist of items... please.

[skshetry]

It would be nice to have a bash syntax highlighting for cmd. vscode-yaml does not seem to support it though (redhat-developer/vscode-yaml#714).

Parametrization syntax is not very important.

[dberenbaum]

Checklist of items here:

• We can link the file/folder references in the dvc yaml files so VSCode can open them in a new tab.
• We can register the parameters as symbols, so the user can jump to them on a Cmd+Click on their reference.
• We can provide definitions for the symbols referenced in the variables, for the same reasons.
• Show the values of parameters and variables on hover.
• Linter showing parameters and variables that are missing
• Highlight/goto other dvc.yaml references to the same path, parameter, or variable
• Suggest valid values for parameters, variables, and paths
• Bash syntax highlighting for cmd
• Show interpolated values? (do we need this if we do Stages in sidebar #5181)

[julieg18]

We can link the file/folder references in the dvc yaml files so VSCode can open them in a new tab.

Wasn't this already done in #3175?