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