docs: Add --workspace_status_command

Resolves issue bazelbuild#4220

site/docs/user-manual.html

@@ -2064,6 +2064,62 @@ <h4 id='flag--interface_shared_objects'>
   unnecessarily.
 </p>
 
+<h4 id='flag--workspace_status_command'>
+    <code class='flag'>--workspace_status_command=/path/to/binary</code>
+</h4>
+<p>
+  The <code>--workspace_status_command=&lt;path&gt;</code> flag lets you specify
+  a binary.
+</p>
+<p>
+  Bazel runs this binary before each build. The binary should write key-value
+  pairs to stdout. Bazel partitions the keys into two buckets: "stable" and
+  "volatile". (The names "stable" and "volatile" are a bit counter-intuitive,
+  so don't think much about them.)
+</p>
+<p>
+  Bazel then writes the key-value pairs into two files:
+</p>
+<ul>
+
+  <li>
+    <code>bazel-out/stable-status.txt</code> contains all keys and values where
+    the key's name starts with <code>STABLE_</code>
+  </li>
+  <li>
+    <code>bazel-out/volatile-status.txt</code> contains the rest of the keys and
+    their values.
+  </li>
+
+</ul>
+<p>
+  The contract is:
+</p>
+<ul>
+
+  <li>
+    "stable" keys' values should change rarely, if possible. If the contents of
+    <code>stable-status.txt</code> change, it invalidates the actions that
+    depend on them, e.g. the <code>genrule.cmd</code> if that genrule has
+    <code>stamp=1</code>. In other words, if a stable key's value changes, it'll
+    make Bazel rebuild stamped actions. Therefore the stable status should not
+    contain things like timestamps, because they change all the time, and would
+    make Bazel rebuild the stamped actions with each build.
+  </li>
+  <li>
+    "volatile" keys' values may change often. Bazel expects them to change all
+    the time, like timestamps do, and duly updates the
+    <code>volatile-status.txt</code> file. In order to avoid rebuilding stamped
+    actions all the time though, Bazel pretends that the volatile file never
+    changes. In other words, if the volatile status file is the only one whose
+    contents changed, that will not invalidate actions that depend on it. If
+    other inputs of the actions have changed, then Bazel rebuilds that action,
+    and the action may then use the updated volatile status. But just the
+    volatile status changing alone will not invalidate the action.
+  </li>
+
+</ul>
+
 <h3 id='output-selection-options'>Output selection options</h3>
 <p>
   These options determine what to build or test.