README rewrite (+ CONTRIB updates) #1816
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,20 +4,57 @@ | |
| <!--- [](https://github.com/iterative/vscode-dvc/actions/workflows/continuous-integration.yml) ---> | ||
| <!--- [](https://github.com/iterative/vscode-dvc/actions/workflows/cross-platform-test.yml) ---> | ||
| <!-- [](https://github.com/iterative/vscode-dvc/actions/workflows/dvc-cli-output-test.yml) --> | ||
| [](https://codeclimate.com/repos/608b5886f52398018b00264c/maintainability) | ||
| [](https://codeclimate.com/repos/608b5886f52398018b00264c/test_coverage) | ||
|
|
||
| This [extension] integrates [DVC features] right into the popular [VS Code IDE], | ||
| allowing users of all backgrounds to use DVC. | ||
|
|
||
| > **Note**: We want early adopter feedback! | ||
| > Please let us know what you like and don't like about the extension. Feel free | ||
| > to open [issues in this repo] or reach out via [DVC support] channels. | ||
|
|
||
| [extension]: https://marketplace.visualstudio.com/VSCode | ||
| [dvc features]: https://dvc.org/doc/start | ||
| [vs code ide]: https://code.visualstudio.com/ | ||
| [issues in this repo]: https://github.com/iterative/vscode-dvc/issues | ||
| [dvc support]: https://dvc.org/support | ||
|
|
||
| ## What it does (extension features) | ||
|
|
||
| The DVC Extension augments and adds several [Views], adds special [Editors]. | ||
| Furthermore it exposes these and other DVC functions in the [Command Palette]. | ||
| Specifically: | ||
|
|
||
| - It provides _Editors_ to manage [Experiments][exp-view] and display | ||
| [Plots][plots-view] as _Tabs_ in the IDE. | ||
| - Adds a [DVC Tracked] panel to the _Explorer_ view. This shows a tree of the | ||
| data that DVC is tracking, with real-time file/dir [states] and options to | ||
| [synchronize] them (from/to remote storage). | ||
| - Adds a [DVC panel] to the _Source Control_ view to list the [workspace | ||
| status]. You can [restore] or reset project versions (based on the current Git | ||
| `HEAD` commit) as well as [manage new and existing data] from here. | ||
jorgeorpinel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Adds a brand-new [DVC View] (<img | ||
| src="https://user-images.githubusercontent.com/1477535/171570901-9012413c-f0bb-41d9-9a45-2653b4e3f1fe.png" | ||
| alt="DVC logo" style="height: 1em;"/> icon in the Activity Bar) with panels to | ||
|
There was a problem hiding this comment.
There was a problem hiding this comment. fixed this by changing from style to height. |
||
| visualize and manage [DVC Experiments]. | ||
| - Registers several [commands] in the _Command Palette_. | ||
| - Includes a [DVC channel] for the _Output_ panel (useful for | ||
| [debugging](#debugging)). | ||
|
|
||
| [views]: https://code.visualstudio.com/docs/getstarted/userinterface#_views | ||
| [editors]: | ||
| https://code.visualstudio.com/docs/getstarted/userinterface#_open-editors | ||
| [command palette]: | ||
| https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette | ||
|
|
||
| [exp-view]: extension/resources/walkthrough/experiments-table.md | ||
| [plots-view]: extension/resources/walkthrough/plots.md | ||
| [dvc tracked]: extension/resources/walkthrough/tracked-explorer.md | ||
|
There was a problem hiding this comment. All of these relative links need to get changed to the github hosted ones or they won't work in product either There was a problem hiding this comment. Used absolute paths for all of these links because viewers could be:
|
||
| [dvc panel]: extension/resources/walkthrough/source-control-management.md | ||
| [dvc view]: extension/resources/walkthrough/view-container.md | ||
| [command palette]: extension/resources/walkthrough/command-palette.md | ||
| [dvc output]: # | ||
jorgeorpinel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Quick Start | ||
|
|
||
|
|
@@ -27,6 +64,16 @@ existing [support channels](https://dvc.org/support). | |
| [Install the DVC extension for Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-gallery). | ||
| - **Step 3.** See Walkthrough. | ||
|
|
||
| ### Learn more about DVC (Data Version Control) | ||
|
|
||
| View [more resources](extension/resources/walkthrough/dvc-learn-more.md). | ||
|
|
||
| ## Configuration | ||
|
|
||
| <!-- TODO --> | ||
|
|
||
| See the .vscode/ dir. | ||
jorgeorpinel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Useful commands | ||
|
|
||
| Open the Command Palette (`F1` or ⇧⌃P on Windows/Linux or ⇧⌘P on macOS) and type | ||
|
|
@@ -40,16 +87,18 @@ in one of the following commands: | |
| | `DVC: Show Experiments` | Show an interactive version of DVC's `exp show` [command](https://dvc.org/doc/command-reference/exp/show). | | ||
| | `DVC: Show Plots` | Show an interactive version of DVC's `plots diff` [command](https://dvc.org/doc/command-reference/plots/diff). | | ||
|
|
||
| ## Debugging | ||
|
There was a problem hiding this comment. It might be helpful to mention https://github.com/iterative/vscode-dvc/issues again here and try to describe which issues should go where. Or should we just give one channel for issues and leave it to our internal teams to move issues as needed? There was a problem hiding this comment. I'm using Discord first and then link to GH issues in both places now. I think people will mostly know what each channel is for, probably preferring the chat in most cases, esp. for beginner questions. |
||
|
|
||
| ### The DVC Extension | ||
|
|
||
| Please see the DVC [channel] in the IDE's _Output_ panel to see the underlying | ||
| DVC commands being run, as wel as their error output. Feel free to share this | ||
jorgeorpinel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| with us via [DVC support]. | ||
|
|
||
| [channel]: | ||
| https://code.visualstudio.com/api/extension-capabilities/common-capabilities#output-channel | ||
|
|
||
| ### Your DVC project | ||
|
|
||
| Due to the way DVC pipelines run scripts of any language from the command line, | ||
| users must debug pipeline scripts (e.g. `train.py`) standalone in whatever way | ||
|
|
@@ -61,10 +110,6 @@ pipelines, and most scripts are capable of running outside of DVC. | |
| See development docs and contributing guidelines in | ||
| [CONTRIBUTING.md](CONTRIBUTING.md) | ||
|
|
||
mattseddon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## Data and telemetry | ||
|
|
||
| The DVC Extension for Visual Studio Code collects usage data and sends it to | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ideally, the readme should start with value-proposition (not too DVC specific) with following competitive advantages (can be specific). Examples (
Why TPI/MLEM?is competitive advantages):There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ivan just added value-proposition & competitive advantages in the beginning of this doc:
https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit#
PS: It is the 1st iteration (please suggest changes) but it gives an idea how to describe the product.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought the value prop was that it brings DVC into VSC 😅
But I think you're saying that the value is that of the parts of DVC included in the extension + being able to use them visually in the IDE... ⏳
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We discussed that format and I thought we agreed that those 2 lists (features vs. advantages) tend to be redundant (probably OK for TPI but I'm still not sure about MLEM).
Anyway, I'll go with that for now so we can move on.