#306 dvc-file-format updated

static/docs/commands-reference/add.md

@@ -126,11 +126,18 @@ outs:
     md5: d8acabbfd4ee51c95da5d7628c7ef74b
     metric: false
     path: data.xml.jpg
+meta: #key to contain arbitary user data
+  name: John
+  email: john@xyz.com
 ```
 
 This is a standard DVC stage file with only an `outs` entry. The checksum should
 correspond to an entry in the cache.
 
+If user overwrites the `.dvc` file, comments and meta values are not preserved
+between multiple executions of `dvc add` command.
+
+
 ```dvc
 $ file .dvc/cache/d8/acabbfd4ee51c95da5d7628c7ef74b
 

static/docs/commands-reference/import.md

@@ -195,6 +195,9 @@ The `etag` field in the DVC file contains the ETag recorded from the HTTP
 request. If the remote file changes, the ETag changes, letting DVC know when the
 file has changed.
 
+While executing `dvc import` command, if user overwrites the `.dvc` file,
+comments and meta values are not preserved between multiple executions.
+
 ## Example: Detecting remote file changes
 
 What if that remote file is one which will be updated regularly? The project

static/docs/commands-reference/run.md

@@ -159,6 +159,8 @@ To track the changes with git run:
 
 	git add .gitignore metric.dvc
 ```
+While executing `dvc run` command, if user overwrites the `.dvc` file, comments 
+and meta values are not preserved between multiple executions.
 
 - Execute a Python script as a DVC pipeline step. Stage file name is not
   specified, so a `model.p.dvc` stage file is created:

static/docs/user-guide/dvc-file-format.md

@@ -30,6 +30,12 @@ outs:
       xpath: AUC
     path: metrics.json
 locked: True
+
+# Comments are persisted between multiple executions of dvc repro/commit.
+# Comments are not persisted between multiple executions of dvc run/add/import.
+ meta: # key to contain arbitary user data
+  name: John
+  email: john@xyz.com
 ```
 
 ## Structure
@@ -60,3 +66,14 @@ A metric entry consists of such fields:
 - `type`: type of the metrics file (e.g. raw/json/tsv/htsv/csv/hcsv);
 - `xpath`: path within the metrics file to the metrics data(e.g. `AUC.value` for
   `{"AUC": {"value": 0.624321}}`);
+
+A meta entry consists of `key:value` pairs such as `name: john`. A meta entry
+can have any structure and contain any number of attributes. `"meta: string"` is
+also possible, it doesn't necessarily need to contain dictionary always.
+
+Comments can be added to the .dvc file using `# comment` syntax. Comments and
+meta values are preserved between multiple executions of `dvc repro` and
+`dvc commit` commands.
+
+If user overwrites the file, comments and meta values are not preserved between
+multiple executions of `dvc run`,`dvc add`,`dvc import` commands.