From 98deb29bbefebdd095842c2ad72f6aa644701b51 Mon Sep 17 00:00:00 2001 From: "Mr. Outis" Date: Wed, 4 Dec 2019 23:16:07 -0600 Subject: [PATCH] user guide: add concept of well-behaved commands --- static/docs/user-guide/index.md | 3 +++ static/docs/user-guide/well-behaved-command.md | 12 ++++++++++++ 2 files changed, 15 insertions(+) create mode 100644 static/docs/user-guide/well-behaved-command.md diff --git a/static/docs/user-guide/index.md b/static/docs/user-guide/index.md index c015aff79f..b1315b097c 100644 --- a/static/docs/user-guide/index.md +++ b/static/docs/user-guide/index.md @@ -27,6 +27,9 @@ guides related to contributing to this [DVC-file](/doc/user-guide/dvc-files-and-directories) dependencies. - [Managing External Data](/doc/user-guide/managing-external-data) explains both external outputs and external cache. +- [Writing well-behaved commands](/doc/user-guide/well-behaved-command) goes + through the few technicalities that you need to take into account when using + DVC to run your commands. - [Contributing](/doc/user-guide/contributing) is related with getting involved directly in developing DVC. Contributors are very welcomed in our [community](/support)! diff --git a/static/docs/user-guide/well-behaved-command.md b/static/docs/user-guide/well-behaved-command.md new file mode 100644 index 0000000000..bdb84c7b13 --- /dev/null +++ b/static/docs/user-guide/well-behaved-command.md @@ -0,0 +1,12 @@ +# Writing well-behaved commands + +DVC is simple to use, you only need to wrap your commands with `dvc run`, and +define your dependencies and outputs. + +To prevent unexpected behaviors, ideally, your commands should follow some +principles: + +- Read exclusively from specified dependencies +- Write exclusively to specified outputs +- Completely rewrite the outputs (do not append) +- Stop reading and writing when the command exits