user guide: add concept of well-behaved commands

iterative · Dec 5, 2019 · 98deb29 · 98deb29
1 parent 0a0d69a
commit 98deb29
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 0 deletions.
diff --git 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
@@ -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