Added doc's for workspace reset --softpointswaves/softreset

3 files changed, 45 insertions, 0 deletions

diff --git a/doc/sessions/developing.run b/doc/sessions/developing.run
index 1ae4eb5ad..4cbb40c32 100644
--- a/doc/sessions/developing.run
+++ b/doc/sessions/developing.run
@@ -34,6 +34,11 @@ commands:
   output: ../source/sessions/developing-shell-after-changes.html
   command: shell hello.bst -- hello
 
+# Soft Reset
+- directory: ../examples/developing/
+  output: ../source/sessions/developing-soft-reset.html
+  command: workspace reset --soft hello.bst
+
 # Close workspace
 - directory: ../examples/developing/
   output: ../source/sessions/developing-close-workspace.html
diff --git a/doc/source/developing/workspaces.rst b/doc/source/developing/workspaces.rst
index 653716f72..e4ad66da8 100644
--- a/doc/source/developing/workspaces.rst
+++ b/doc/source/developing/workspaces.rst
@@ -70,6 +70,32 @@ This gives us the new message we changed in hello.c.
 From this point we have several options. If the source is under version control
 we can commit our changes and push them to the remote repository.
 
+Making bigger changes
+---------------------
+
+The first time you build with your workspace BuildStream behaves very similarly to
+normal. However for subsequent builds it does not run the configuration commands and
+only runs the build commands. This can result in significant speed ups as the configuration
+commands can be slow (maybe 20+ minutes for a moderate sized element)
+
+Sometimes you do need to rerun the configuration command for a open workspace, this
+can be done by resetting the workspace, and then running a build. However this will
+cause all of your incremental work to be lost. In this case running a soft reset will
+reset the trigger to run the configuration commands but will not change any files in you
+workspace.
+
+Reasons to soft reset a workspace include:
+  * changing the configuration command of a element.
+  * adding a new source that the configure command will spot and enable more code.
+
+The soft reset can be performed by:
+
+.. raw:: html
+   :file: ../sessions/developing-soft-reset.html
+
+Then the next build will include the configuration commands. You must reset the workspace
+every time you wish to trigger the configuration commands as only the first build
+after the reset will run them.
 
 Closing your workspace
 ----------------------
diff --git a/doc/source/sessions-stored/developing-soft-reset.html b/doc/source/sessions-stored/developing-soft-reset.html
new file mode 100644
index 000000000..beb8c7f68
--- /dev/null
+++ b/doc/source/sessions-stored/developing-soft-reset.html
@@ -0,0 +1,14 @@
+<!--
+    WARNING: This file was generated with bst2html.py
+-->
+<div class="highlight" style="font-size:x-small"><pre>
+<span style="color:#C4A000;font-weight:bold">user@host</span>:<span style="color:#3456A4;font-weight:bold">~/developing</span>$ bst workspace reset --soft hello.bst
+
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading elements
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Loading elements
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving elements
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving elements
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#3465A4"><span style=""><span style="opacity:0.5">START  </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">00</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#4E9A06"><span style=""><span style="opacity:0.5">SUCCESS</span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Resolving cached state
+<span style="color:#06989A"><span style="opacity:0.5">[</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">--</span><span style="color:#06989A"><span style="opacity:0.5">][</span></span>        <span style="color:#06989A"><span style="opacity:0.5">][</span></span><span style="color:#C4A000"> main</span><span style="color:#06989A"><span style="opacity:0.5">:</span></span><span style="color:#C4A000">core activity                 </span><span style="color:#06989A"><span style="opacity:0.5">] </span></span><span style="color:#75507B"><span style=""><span style="opacity:0.5">INFO   </span></span></span><span style="color:#06989A"><span style="opacity:0.5"> </span></span>Reset workspace state for hello.bst at: /home/user/projects/buildstream/buildstream/doc/examples/developing/workspace_hello
+</pre></div>