diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000000..1b763b1bae
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1 @@
+CHANGELOG.md
diff --git a/.vscode/settings.json b/.vscode/settings.json
index a2efe89736..12eb1b06db 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -11,6 +11,7 @@
"appdirs",
"camelcase",
"chokidar",
+ "Codespaces",
"conda",
"datapoint",
"datapoints",
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 61d5e42c97..2732901da2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,55 +1,49 @@
-# Feedback
+## Feedback
-See something that should be changed? Want to request a new feature? Open
-[a GitHub Issue!](https://github.com/iterative/vscode-dvc/issues)
+See something that should be changed? Want to request a new feature? Open an
+[issue on GitHub](https://github.com/iterative/vscode-dvc/issues)!
-# Development Setup
+## Pull requests
-Ensure [Yarn](https://yarnpkg.com/) and
-[Visual Studio Code](https://code.visualstudio.com) are installed.
-
-It is recommended that you have a DVC project available to test the extension
-against. We have provided [the demo project](#the-demo-project) as part of this
-repo but feel free to use any DVC project that you have available.
-
-To enable formatting on save in VS Code, install the `esbenp.prettier-vscode`
-extension. This is optional, but highly recommended as PRs with improper format
-will be blocked from merge until the issue is fixed.
+You may also submit a change request to this repository directly
+[from here](https://github.com/iterative/vscode-dvc/pulls). Contributions are
+highly appreciated!
-
+> 💡 **Tip**: To enable formatting on save in VS Code, install the
+> `esbenp.prettier-vscode` extension. This is highly recommended as PRs with
+> improper format will be blocked from merge until fixed.
-Note: When using any project that relies on an isolated python environment
-(conda, venv, etc) the
-[ms-python.python](https://github.com/Microsoft/vscode-python) extension needs
-to be installed into VS Code. It is used by this extension to locate and utilize
-the required environment.
+## Development environment
-## Development Environment
+The development environment allows contributors to test their changes to the
+extension. The local repository source is built and loaded into the Extension
+Development Host.
-The development environment allows contributors to test out the extension. The
-current repository source is built and loaded into the Extension Development
-Host as an Extension.
-
-Please be aware that having a separate (`.vsix`) version of the extension
-installed will cause all kinds of chaos in your development environment.
+First, ensure that [Yarn](https://yarnpkg.com/) and
+[Visual Studio Code](https://code.visualstudio.com) are installed.
-- Open the monorepo root as a project in VS Code
+- Open this repository's root directory as a project in VS Code.
- Run `Tasks: Run Build Task` (Ctrl+Shift+b) to start the extension and webview
development servers (alternatively run `yarn dev-server` from the terminal).
+ > **Warning**: Having a separate (`.vsix`) version of the extension installed
+ > may cause all kinds of chaos in your development environment.
+
- Open the Extension Development Host, a child instance of VS Code with the
results of the dev servers installed as an extension, with `Start Debugging`
- (f5).
- Note: selecting the `Run Extension` option when running the debugger will
- prevent all other extensions from being loaded into the VS code instance. This
- will improve the performance of VS code but can cause certain DVC commands to
- fail if the project uses an isolated python environment (see
- [this note](#note)).
+ (f5).
-- Open the demo or another DVC project in the Extension Development Host; VS
- Code will remember the last project opened, so this step only has to be done
- once.
+ > **Note**: using the `Run Extension` command when running the debugger will
+ > prevent all other extensions from loading into VS Code. This will improve
+ > the performance of VS Code but can cause certain DVC commands to fail if the
+ > project uses an isolated python environment (see [this warning](#warning)).
+
+- Open a DVC project in the Extension Development Host. VS Code will remember
+ the last project opened, so this step only has to be done once.
+
+ > **Note**: We have provided a demo project as part of this repo, but feel
+ > free to use any DVC project that you have available.
## The demo project
@@ -75,9 +69,17 @@ encouraged to try other DVC repositories- especially real-world cases!
environment to be loaded.
- This will happen automatically IF the `ms-python.python` extension is
- installed within the VS code instance that you are developing against.
+ installed within the VS Code instance that you are developing against.
+
+
-## React Component Development with Storybook
+> **Warning**
+> When using any project that relies on an isolated Python environment (`conda`,
+> `venv`, etc.), Microsoft's
+> [Python extension](https://github.com/Microsoft/vscode-python) is required.
+> It's used by this extension to locate and utilize the required environment.
+
+## React component development with Storybook
Start Storybook with `yarn storybook` in either the monorepo root or the
`webview` project, and you can develop the React components this plugin uses
@@ -87,9 +89,3 @@ There are some discrepancies between the Storybook environment and the
environment of a real VS Code extension, custom themes being one big one. Always
make sure to try out changed components in the full dev environment before
merging!
-
-# Resources
-
-Check out the
-[Resources page](https://github.com/iterative/vscode-dvc/wiki/Resources) of our
-GitHub wiki for a list of relevant docs and related projects.
diff --git a/README.md b/README.md
index 40d846f342..f00bd09ff4 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,121 @@
+
+
# DVC Extension for Visual Studio Code
-
-
-
-
+[](https://https://marketplace.visualstudio.com/items?itemName=Iterative.dvc)
+[](https://https://marketplace.visualstudio.com/items?itemName=Iterative.dvc)
+[](https://https://marketplace.visualstudio.com/items?itemName=Iterative.dvc)
+[](https://https://marketplace.visualstudio.com/items?itemName=Iterative.dvc)
+[](https://github.com/iterative/vscode-dvc/actions/workflows/continuous-integration.yml)
[](https://codeclimate.com/repos/608b5886f52398018b00264c/maintainability)
[](https://codeclimate.com/repos/608b5886f52398018b00264c/test_coverage)
-A [Visual Studio Code](https://code.visualstudio.com/)
-[extension](https://marketplace.visualstudio.com/VSCode) that aims to allow
-users of all technical backgrounds to effectively use [DVC](https://dvc.org/).
-
-## Current State
-
-We want early adopter feedback! Please let us know what you like and don't like
-about the extension. Feel free to reach out in this repository's
-[issues](https://github.com/iterative/vscode-dvc/issues) or via any of the other
-existing [support channels](https://dvc.org/support).
-
-## Quick Start
-
-- **Step 1.**
- [Install a supported version of DVC on your system](https://dvc.org/doc/install)
-- **Step 2.**
- [Install the DVC extension for Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-gallery).
-- **Step 3.** See Walkthrough.
+Run, compare, visualize, and track machine learning experiments right in VS
+Code. This extension uses [DVC](https://dvc.org/), an open-source data
+versioning and ML experiment management tool. No additional services or
+databases are required.
+
+
+
+- **Experiment tracking**: Record training data, parameters, and metrics on top
+ of [Git](https://git-scm.com/). Navigate your experiments, compare their
+ results, and find the best ML models.
+- **Visualization**: Plot performance data in a customizable dashboard including
+ one or more overlaid experiments.
+- **Live tracking**: Capture and see metrics changing in real time.
+- **Reproducibility**: Make sure that anyone can recover or confirm previous
+ experiments, and run new experiments based on their results.
+- **Data Management**: Handle and version large datasets, files, and models
+ effectively right from VS Code.
+
+> **Note**: We are in public beta and welcome early adopter feedback!
+> Feel free to reach out [via Discord] or open [issues in GitHub].
+>
+> [issues in github]: https://github.com/iterative/vscode-dvc/issues
+> [via discord]: https://discord.gg/BGCjJHvDHt
+
+### Why prefer this extension?
+
+- Enjoy the best developer experience with the first experiment tracking
+ interface for an IDE.
+- No external servers, databases, subscriptions, etc. Data stays fully under
+ your control and your existing Git hosting is used to share and collaborate.
+- Go beyond a simple metrics dashboard with complete ML experiments that include
+ metrics, code, and data. Powered by [DVC experiment
+ versioning][dvc experiments].
+- Implement [data versioning] on top of your favorite cloud storage, such as
+ Amazon S3, Azure Blob Storage, Google Cloud Storage, NFS, etc.
+
+[dvc experiments]:
+ https://dvc.org/doc/user-guide/experiment-management/experiments-overview
+[data versioning]: https://dvc.org/doc/use-cases/versioning-data-and-model-files
+
+## Quick start
+
+1. [Install DVC](https://dvc.org/doc/install) on your system.
+2. Install [this extension] in VS Code.
+3. Follow the **Get Started** page that pops up!
+
+
+> 💡 Feel free to try our [example DVC project] first! Opening it [with Github
+> Codespaces] will include this extension automatically.
+
+
+
+[this extension]:
+ https://marketplace.visualstudio.com/items?itemName=Iterative.dvc
+[example dvc project]: https://github.com/iterative/example-get-started
+[with github codespaces]:
+ https://docs.github.com/en/codespaces/getting-started/quickstart#creating-your-codespace
+
+### Learn more about DVC (Data Version Control)
+
+See the DVC documentation to Get Started with [Experiment Versioning] or [Data
+Management]. For deeper learning, try our [free course]!
+
+[experiment versioning]: https://dvc.org/doc/start/experiments
+[data management]: https://dvc.org/doc/start/data-management
+[free course]: https://learn.iterative.ai/
+
+
+
+## What you get
+
+This extension augments VS Code in the following ways:
+
+- Adds a brand-new new **[DVC View]** (
icon in the Activity Bar) with panels to
+ visualize and manage [DVC Experiments].
+- Provides special _Editors_ to manage **[Experiments]** and display **[Plots]**
+ in IDE _Tabs_.
+- Adds a **[DVC Tracked]** panel to the _Explorer_ view. This shows a tree of
+ the data files and directories tracked by DVC, including their state, and
+ options to [synchronize] them (from/to remote storage).
+- Adds a **[DVC panel]** to the _Source Control_ view to display 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.
+- Registers several **Commands** in the _[Command Palette]_ (see next section).
+- Includes a DVC channel for the _Output_ panel (useful for
+ [debugging](#debugging)).
+
+[dvc view]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/view-container.md
+[experiments]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/experiments-table.md
+[plots]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/plots.md
+[command palette]:
+ https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette
+[dvc tracked]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/dvc-tracked-files.md
+[synchronize]: https://dvc.org/doc/start/data-management#storing-and-sharing
+[dvc panel]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/dvc-tracked-files.md
+[workspace status]:
+ https://dvc.org/doc/command-reference/status#local-workspace-status
+[restore]: https://dvc.org/doc/start/data-management#switching-between-versions
## Useful commands
@@ -40,16 +130,46 @@ 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). |
-## Features
+Learn more about the extension's [commands].
+
+[commands]:
+ https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/command-palette.md
+
+## Configuration
+
+These are the VS Code [settings] available for the Extension:
-- [Command Palette](extension/resources/walkthrough/command-palette.md)
-- [Source Control Management](extension/resources/walkthrough/source-control-management.md)
-- [Tracked Resources](extension/resources/walkthrough/tracked-explorer.md)
-- [DVC View Container](extension/resources/walkthrough/view-container.md)
-- [Experiments Table](extension/resources/walkthrough/experiments-table.md)
-- [Plots](extension/resources/walkthrough/plots.md)
+[settings]: https://code.visualstudio.com/docs/getstarted/settings
-### Debugging
+| **Option** | **Description** |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dvc.dvcPath` | Path or shell command to the DVC binary. Required unless Microsoft's [Python extension] is installed and the `dvc` package found in its environment. |
+| `dvc.pythonPath` | Path to the desired Python interpreter to use with DVC. Required when using a virtual environment. |
+| `dvc.doNotShowWalkthroughAfterInstall` | Do not prompt to show the Get Started page after installing. Useful for pre-configured development environments |
+| `dvc.doNotRecommendRedHatExtension` | Do not prompt to install the Red Hat YAML extension, which helps with DVC YAML schema validation (`dvc.yaml` and `.dvc` files). |
+| `dvc.doNotShowCliUnavailable` | Do not warn when the workspace contains a DVC project but the DVC binary is unavailable. |
+| `dvc.doNotShowUnableToFilter` | Do not warn before disabling auto-apply filters when these would result in too many experiments being selected. |
+
+> **Note** that the `Setup The Workspace` command helps you set up the basic
+> ones at the [Workspace level] (saved to `.vscode/setting.json`).
+
+[python extension]:
+ https://marketplace.visualstudio.com/items?itemName=ms-python.python
+[workspace level]:
+ https://code.visualstudio.com/docs/getstarted/settings#_workspace-settings
+
+## Debugging
+
+### The DVC Extension
+
+Please see the DVC [channel] in the IDE's _Output_ panel to see the underlying
+DVC commands being run, as well as their error output. Feel free to share this
+with us [via Discord] or use it to report [issues in GitHub].
+
+[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
@@ -58,12 +178,10 @@ pipelines, and most scripts are capable of running outside of DVC.
## Contributing
-See development docs and contributing guidelines in
-[CONTRIBUTING.md](CONTRIBUTING.md)
-
-## Explore
+See the development and contributing guidelines in
+[CONTRIBUTING.md](https://github.com/iterative/vscode-dvc/blob/main/CONTRIBUTING.md).
-View [more resources](extension/resources/walkthrough/dvc-learn-more.md).
+
## Data and telemetry
diff --git a/extension/resources/overview.gif b/extension/docs/overview.gif
similarity index 100%
rename from extension/resources/overview.gif
rename to extension/docs/overview.gif
diff --git a/extension/docs/walkthroughs.png b/extension/docs/walkthroughs.png
new file mode 100644
index 0000000000..a32d627289
Binary files /dev/null and b/extension/docs/walkthroughs.png differ
diff --git a/extension/package.nls.json b/extension/package.nls.json
index 5cfca5d7df..ece5b5eaa2 100644
--- a/extension/package.nls.json
+++ b/extension/package.nls.json
@@ -68,16 +68,16 @@
"command.views.experimentsTree.selectExperiments": "Select Experiments to Display in Plots",
"command.views.plotsPathsTree.selectPlots": "Select Plots to Display",
"command.views.plotsPathsTree.refreshPlots": "Refresh Plots for Selected Experiments",
- "config.doNotRecommendRedHatExtension.description": "Do not prompt to install the Red Hat YAML extension to assist with DVC YAML schema validation.",
- "config.doNotRecommendRedHatExtension.title": "Do not prompt to install the Red Hat YAML extension.",
- "config.doNotShowCliUnavailable.description": "Do not warn when the workspace contains a DVC project but the CLI is inaccessible.",
- "config.doNotShowCliUnavailable.title": "Do not warn when the CLI is inaccessible.",
- "config.doNotShowWalkthroughAfterInstall.description": "Do not prompt to show the extension walkthrough after installing.",
- "config.doNotShowWalkthroughAfterInstall.title": "Do not prompt to show the extension walkthrough.",
- "config.doNotShowUnableToFilter.description": "Do not warn before disabling auto-apply filters when applying the selected filters would result in too many experiments being selected.",
+ "config.doNotRecommendRedHatExtension.description": "Do not prompt to install the Red Hat YAML extension, which helps with DVC YAML schema validation.",
+ "config.doNotRecommendRedHatExtension.title": "Do not recommend the YAML extension.",
+ "config.doNotShowCliUnavailable.description": "Do not warn when the workspace contains a DVC project but the DVC binary is unavailable.",
+ "config.doNotShowCliUnavailable.title": "Do not warn when DVC is unavailable.",
+ "config.doNotShowWalkthroughAfterInstall.description": "Do not prompt to show the Get Started page after installing. Useful for pre-configured development environments",
+ "config.doNotShowWalkthroughAfterInstall.title": "Do not show the Get Started page.",
+ "config.doNotShowUnableToFilter.description": "Do not warn before disabling auto-apply filters when these would result in too many experiments being selected.",
"config.doNotShowUnableToFilter.title": "Do not warn before disabling auto-apply filters to experiment selection.",
- "config.dvcPath.description": "Call DVC from this path. Follows Python extension when blank.",
- "config.dvcPath.title": "DVC CLI Path",
- "config.pythonPath.description": "Required virtual environment's Python interpreter path. Overrides any other extension's settings for the DVC CLI.",
- "config.pythonPath.title": "DVC Python Interpreter Path"
+ "config.dvcPath.description": "Path or shell command to the DVC binary. Required unless Microsoft's Python extension is installed and the `dvc` package found in its environment.",
+ "config.dvcPath.title": "DVC Path (or shell command)",
+ "config.pythonPath.description": "Path to the desired Python interpreter to use with DVC. Required when using a virtual environment. Overrides any other extension's settings for this extension's purposes.",
+ "config.pythonPath.title": "Python Interpreter"
}
diff --git a/extension/resources/banner.png b/extension/resources/banner.png
new file mode 100644
index 0000000000..f678f5c5ce
Binary files /dev/null and b/extension/resources/banner.png differ