From a7bdc1e82c180f7a579e2f33d8eef4945a116add Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 17:06:02 -0500 Subject: [PATCH 01/10] readme: intro updates (VSCE) --- README.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index ee63795af2..072212daa5 100644 --- a/README.rst +++ b/README.rst @@ -2,12 +2,12 @@ `Website `_ • `Docs `_ +• `VS Code Extension `_ • `Blog `_ • `Twitter `_ • `Chat (Community & Support) `_ • `Tutorial `_ • `Mailing List `_ -• `VS Code Extension `_ |CI| |Maintainability| |Coverage| |VS Code| |DOI| @@ -15,8 +15,10 @@ | -**Data Version Control** or **DVC** helps you develop reproducible machine -learning projects: +**Data Version Control** or **DVC** is a command line tool and +`VS Code Extension +`_ to help +you develop reproducible machine learning projects: #. **Version** your data and models. Store them in your cloud storage but keep their version info in your Git repo. @@ -26,9 +28,7 @@ learning projects: #. **Track** experiments in your local Git repo (no servers needed). -#. **Compare** any data, code, parameters, metrics, or plots from the command - line or in `VS Code - `_. +#. **Compare** any data, code, parameters, modelhttps://www.youtube.com/watch?v=IYhVmD-_wRometrics, or performance plots #. **Share** experiments and automatically reproduce anyone's experiment. From 0f28652609b53fb1735793d4809954fe455b816d Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 17:27:02 -0500 Subject: [PATCH 02/10] readme: blocks to link to DVC GS --- README.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 072212daa5..9b45b1168a 100644 --- a/README.rst +++ b/README.rst @@ -38,8 +38,9 @@ you develop reproducible machine learning projects: How DVC works ============= -We encourage you to read our `Get Started `_ guide to better understand what DVC -is and how it can fit your scenarios. + We encourage you to read our `Get Started + `_ guides to better understand what DVC + does and how it can fit your scenarios. The easiest (but not perfect!) *analogy* to describe it: DVC is Git (or Git-LFS to be precise) & Makefiles made right and tailored specifically for ML and Data Science scenarios. @@ -62,7 +63,10 @@ the `Get Started `_ tutorial to learn more. Quick start =========== -Please read `Get Started `_ guide for a full version. Common workflow commands include: + Please read our `Get Started `_ guides for + a full version. + +Common workflow commands include: +-----------------------------------+----------------------------------------------------------------------------+ | Step | Command | From b84366f98379f7490fd525636a3428c8132b17e6 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 17:35:39 -0500 Subject: [PATCH 03/10] readme: Link current Quick start to Cmd Ref --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 9b45b1168a..041b3279a1 100644 --- a/README.rst +++ b/README.rst @@ -63,18 +63,18 @@ the `Get Started `_ tutorial to learn more. Quick start =========== - Please read our `Get Started `_ guides for - a full version. + Please read our `Command Reference https://dvc.org/doc/command-reference>`_ + for a full reference. Common workflow commands include: +-----------------------------------+----------------------------------------------------------------------------+ -| Step | Command | +| Task | Terminal | +===================================+============================================================================+ | Track data | | ``$ git add train.py`` | | | | ``$ dvc add images.zip`` | +-----------------------------------+----------------------------------------------------------------------------+ -| Connect code and data by commands | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` | +| Connect code and data | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` | | | | ``$ dvc run -n train -d images/ -d train.py -o model.p python train.py`` | +-----------------------------------+----------------------------------------------------------------------------+ | Make changes and reproduce | | ``$ vi train.py`` | From 04fd858e436ec4eebf8ea53dc90285214028bea8 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 17:54:45 -0500 Subject: [PATCH 04/10] readme: add VS Code to Installation list + formatting --- README.rst | 64 +++++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/README.rst b/README.rst index 041b3279a1..d48701d9f2 100644 --- a/README.rst +++ b/README.rst @@ -15,10 +15,7 @@ | -**Data Version Control** or **DVC** is a command line tool and -`VS Code Extension -`_ to help -you develop reproducible machine learning projects: +**Data Version Control** or **DVC** is a command line tool and `VS Code Extension `_ to help you develop reproducible machine learning projects: #. **Version** your data and models. Store them in your cloud storage but keep their version info in your Git repo. @@ -60,13 +57,13 @@ specify all steps required to produce a model: input dependencies including data and output information to be saved. See the quick start section below or the `Get Started `_ tutorial to learn more. -Quick start -=========== +Quick start (CLI) +================= Please read our `Command Reference https://dvc.org/doc/command-reference>`_ for a full reference. -Common workflow commands include: +A common command-line interface workflow includes: +-----------------------------------+----------------------------------------------------------------------------+ | Task | Terminal | @@ -91,14 +88,21 @@ Common workflow commands include: Installation ============ -There are four options to install DVC: ``pip``, Homebrew, Conda (Anaconda) or an OS-specific package. +There are several ways to install DVC: in VS Code; using ``snap``, ``choco``, ``brew``, ``conda``, ``pip``; or with an OS-specific package. Full instructions are `available here `_. -To use with VS Code, install DVC and then install the `DVC Extension -`_. +Visual Studio Code Extension +---------------------------- -Snap (Snapcraft/Linux) ----------------------- +|VS Code| + +To get DVC features embedded right into your VS Code IDE, install the `DVC Extension `_ from the Marketplace. + + Note: You'll also have to install core DVC in your system in one of the + other ways listed below. The Extension will guide you if needed. + +Snapcraft (Linux) +----------------- |Snap| @@ -107,11 +111,10 @@ Snap (Snapcraft/Linux) snap install dvc --classic This corresponds to the latest tagged release. -Add ``--beta`` for the latest tagged release candidate, -or ``--edge`` for the latest ``main`` version. +Add ``--beta`` for the latest tagged release candidate, or ``--edge`` for the latest ``main`` version. -Choco (Chocolatey/Windows) --------------------------- +Chocolatey (Windows) +-------------------- |Choco| @@ -119,8 +122,8 @@ Choco (Chocolatey/Windows) choco install dvc -Brew (Homebrew/Mac OS) ----------------------- +Brew (mac OS) +------------- |Brew| @@ -128,8 +131,8 @@ Brew (Homebrew/Mac OS) brew install dvc -Conda (Anaconda) ----------------- +Anaconda (Any platform) +----------------------- |Conda| @@ -138,11 +141,10 @@ Conda (Anaconda) conda install -c conda-forge mamba # installs much faster than conda mamba install -c conda-forge dvc -Depending on the remote storage type you plan to use to keep and share your data, you might need to -install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`. +Depending on the remote storage type you plan to use to keep and share your data, you might need to install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`. -pip (PyPI) ----------- +PyPI (Python) +------------- |PyPI| @@ -150,10 +152,8 @@ pip (PyPI) pip install dvc -Depending on the remote storage type you plan to use to keep and share your data, you might need to specify -one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all. -The command should look like this: ``pip install dvc[s3]`` (in this case AWS S3 dependencies such as ``boto3`` -will be installed automatically). +Depending on the remote storage type you plan to use to keep and share your data, you might need to specify one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all. +The command should look like this: ``pip install dvc[s3]`` (in this case AWS S3 dependencies such as ``boto3`` will be installed automatically). To install the development version, run: @@ -161,13 +161,13 @@ To install the development version, run: pip install git+git://github.com/iterative/dvc -Package -------- +Package (Platform-specific) +--------------------------- |Packages| -Self-contained packages for Linux, Windows, and Mac are available. The latest version of the packages -can be found on the GitHub `releases page `_. +Self-contained packages for Linux, Windows, and Mac are available. +The latest version of the packages can be found on the GitHub `releases page `_. Ubuntu / Debian (deb) ^^^^^^^^^^^^^^^^^^^^^ From b06bbef3f9c5b8beb0c997c2168f03505486f07e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 17 Jun 2022 19:53:05 -0500 Subject: [PATCH 05/10] Update README.rst Co-authored-by: Dave Berenbaum --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d48701d9f2..dc8b806fb5 100644 --- a/README.rst +++ b/README.rst @@ -153,7 +153,7 @@ PyPI (Python) pip install dvc Depending on the remote storage type you plan to use to keep and share your data, you might need to specify one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all. -The command should look like this: ``pip install dvc[s3]`` (in this case AWS S3 dependencies such as ``boto3`` will be installed automatically). +The command should look like this: ``pip install 'dvc[s3]'`` (in this case AWS S3 dependencies such as ``boto3`` will be installed automatically). To install the development version, run: From d3c0f08f6e35507b36873628e7a45b7294281286 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 20:03:14 -0500 Subject: [PATCH 06/10] readme: add VS Code Extension sction and gif --- README.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index dc8b806fb5..5375bbb330 100644 --- a/README.rst +++ b/README.rst @@ -25,7 +25,7 @@ #. **Track** experiments in your local Git repo (no servers needed). -#. **Compare** any data, code, parameters, modelhttps://www.youtube.com/watch?v=IYhVmD-_wRometrics, or performance plots +#. **Compare** any data, code, parameters, model, or performance plots #. **Share** experiments and automatically reproduce anyone's experiment. @@ -54,16 +54,25 @@ Google Cloud, etc) or any on-premise network storage (via SSH, for example). The DVC pipelines (computational graph) feature connects code and data together. It is possible to explicitly specify all steps required to produce a model: input dependencies including data, commands to run, -and output information to be saved. See the quick start section below or +and output information to be saved. See the quick start sections below or the `Get Started `_ tutorial to learn more. -Quick start (CLI) -================= +Quick start (Visual Studio Code) +================================ + +#. `Install DVC `_ on your system. +#. Install the `DVC extension `_ for VS Code. +#. Follow the **Get Started** page that pops up! + +|VS Code Extension Overview| + +Quick start (command line) +========================== Please read our `Command Reference https://dvc.org/doc/command-reference>`_ for a full reference. -A common command-line interface workflow includes: +A common CLI workflow includes: +-----------------------------------+----------------------------------------------------------------------------+ | Task | Terminal | @@ -261,6 +270,9 @@ Barrak, A., Eghan, E.E. and Adams, B. `On the Co-evolution of ML Pipelines and S :target: https://dvc.org :alt: DVC logo +.. |VS Code Extension Overview| image:: https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/docs/overview.gif + :alt: DVC Extension for VS Code + .. |CI| image:: https://github.com/iterative/dvc/workflows/Tests/badge.svg?branch=main :target: https://github.com/iterative/dvc/actions :alt: GHA Tests From ac96fc520a01c98dd3e1f6f4adb5712dd2677b39 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Fri, 17 Jun 2022 21:20:21 -0500 Subject: [PATCH 07/10] readme: fix link --- README.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 5375bbb330..6ab145b800 100644 --- a/README.rst +++ b/README.rst @@ -69,8 +69,7 @@ Quick start (Visual Studio Code) Quick start (command line) ========================== - Please read our `Command Reference https://dvc.org/doc/command-reference>`_ - for a full reference. + Please read our `Command Reference `_ for a complete list. A common CLI workflow includes: From 5482de3582e366b86fb4923ba95e72cc39a2e37e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sat, 18 Jun 2022 20:53:45 -0500 Subject: [PATCH 08/10] readme: roll back non-vscode changes --- README.rst | 49 +++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 6ab145b800..b6d6ed06c6 100644 --- a/README.rst +++ b/README.rst @@ -35,9 +35,8 @@ How DVC works ============= - We encourage you to read our `Get Started - `_ guides to better understand what DVC - does and how it can fit your scenarios. +We encourage you to read our `Get Started `_ guide to better understand what DVC +is and how it can fit your scenarios. The easiest (but not perfect!) *analogy* to describe it: DVC is Git (or Git-LFS to be precise) & Makefiles made right and tailored specifically for ML and Data Science scenarios. @@ -69,17 +68,15 @@ Quick start (Visual Studio Code) Quick start (command line) ========================== - Please read our `Command Reference `_ for a complete list. - -A common CLI workflow includes: +Please read `Get Started `_ guide for a full version. Common workflow commands include: +-----------------------------------+----------------------------------------------------------------------------+ -| Task | Terminal | +| Step | Command | +===================================+============================================================================+ | Track data | | ``$ git add train.py`` | | | | ``$ dvc add images.zip`` | +-----------------------------------+----------------------------------------------------------------------------+ -| Connect code and data | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` | +| Connect code and data by commands | | ``$ dvc run -n prepare -d images.zip -o images/ unzip -q images.zip`` | | | | ``$ dvc run -n train -d images/ -d train.py -o model.p python train.py`` | +-----------------------------------+----------------------------------------------------------------------------+ | Make changes and reproduce | | ``$ vi train.py`` | @@ -119,10 +116,11 @@ Snapcraft (Linux) snap install dvc --classic This corresponds to the latest tagged release. -Add ``--beta`` for the latest tagged release candidate, or ``--edge`` for the latest ``main`` version. +Add ``--beta`` for the latest tagged release candidate, +or ``--edge`` for the latest ``main`` version. -Chocolatey (Windows) --------------------- +Choco (Chocolatey/Windows) +-------------------------- |Choco| @@ -130,8 +128,8 @@ Chocolatey (Windows) choco install dvc -Brew (mac OS) -------------- +Brew (Homebrew/Mac OS) +---------------------- |Brew| @@ -139,8 +137,8 @@ Brew (mac OS) brew install dvc -Anaconda (Any platform) ------------------------ +Conda (Anaconda) +---------------- |Conda| @@ -149,10 +147,11 @@ Anaconda (Any platform) conda install -c conda-forge mamba # installs much faster than conda mamba install -c conda-forge dvc -Depending on the remote storage type you plan to use to keep and share your data, you might need to install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`. +Depending on the remote storage type you plan to use to keep and share your data, you might need to +install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`. -PyPI (Python) -------------- +pip (PyPI) +---------- |PyPI| @@ -160,8 +159,10 @@ PyPI (Python) pip install dvc -Depending on the remote storage type you plan to use to keep and share your data, you might need to specify one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all. -The command should look like this: ``pip install 'dvc[s3]'`` (in this case AWS S3 dependencies such as ``boto3`` will be installed automatically). +Depending on the remote storage type you plan to use to keep and share your data, you might need to specify +one of the optional dependencies: ``s3``, ``gs``, ``azure``, ``oss``, ``ssh``. Or ``all`` to include them all. +The command should look like this: ``pip install dvc[s3]`` (in this case AWS S3 dependencies such as ``boto3`` +will be installed automatically). To install the development version, run: @@ -169,13 +170,13 @@ To install the development version, run: pip install git+git://github.com/iterative/dvc -Package (Platform-specific) ---------------------------- +Package +------- |Packages| -Self-contained packages for Linux, Windows, and Mac are available. -The latest version of the packages can be found on the GitHub `releases page `_. +Self-contained packages for Linux, Windows, and Mac are available. The latest version of the packages +can be found on the GitHub `releases page `_. Ubuntu / Debian (deb) ^^^^^^^^^^^^^^^^^^^^^ From 8fdaec51521221a9bc1f4fd9a96f38e6dbf7ec16 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Sat, 18 Jun 2022 22:40:43 -0500 Subject: [PATCH 09/10] readme: single QS, VSC gif in Install per https://github.com/iterative/dvc/pull/7916#pullrequestreview-1011465782 and https://github.com/iterative/dvc/pull/7916#pullrequestreview-1011465820 --- README.rst | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index b6d6ed06c6..616efd06f2 100644 --- a/README.rst +++ b/README.rst @@ -56,17 +56,8 @@ specify all steps required to produce a model: input dependencies including data and output information to be saved. See the quick start sections below or the `Get Started `_ tutorial to learn more. -Quick start (Visual Studio Code) -================================ - -#. `Install DVC `_ on your system. -#. Install the `DVC extension `_ for VS Code. -#. Follow the **Get Started** page that pops up! - -|VS Code Extension Overview| - -Quick start (command line) -========================== +Quick start +=========== Please read `Get Started `_ guide for a full version. Common workflow commands include: @@ -106,6 +97,8 @@ To get DVC features embedded right into your VS Code IDE, install the `DVC Exten Note: You'll also have to install core DVC in your system in one of the other ways listed below. The Extension will guide you if needed. +|VS Code Extension Overview| + Snapcraft (Linux) ----------------- From 5a1f9b0a3599a26314b3c627632ce5b8709e2ea3 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Perez Date: Mon, 20 Jun 2022 02:09:42 -0500 Subject: [PATCH 10/10] readme: make VS Code installation into a separate section. per https://github.com/iterative/dvc/pull/7916#pullrequestreview-1011575851 --- README.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 616efd06f2..6e2d7c7161 100644 --- a/README.rst +++ b/README.rst @@ -81,24 +81,25 @@ Please read `Get Started `_ guide for a full ve | | | ``$ dvc push`` | +-----------------------------------+----------------------------------------------------------------------------+ -Installation -============ - -There are several ways to install DVC: in VS Code; using ``snap``, ``choco``, ``brew``, ``conda``, ``pip``; or with an OS-specific package. -Full instructions are `available here `_. - Visual Studio Code Extension ----------------------------- +============================ |VS Code| -To get DVC features embedded right into your VS Code IDE, install the `DVC Extension `_ from the Marketplace. - - Note: You'll also have to install core DVC in your system in one of the - other ways listed below. The Extension will guide you if needed. +To get use DVC as a GUI right from your VS Code IDE, install the `DVC Extension `_ from the Marketplace. +It currently features experiment tracking and data management, and more features (data pipeline support, etc.) are coming soon! |VS Code Extension Overview| + Note: You'll have to install core DVC on your system separately (as detailed + below). The Extension will guide you if needed. + +Installation +============ + +There are several ways to install DVC: in VS Code; using ``snap``, ``choco``, ``brew``, ``conda``, ``pip``; or with an OS-specific package. +Full instructions are `available here `_. + Snapcraft (Linux) -----------------