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

1 files changed, 26 insertions, 0 deletions

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
 ----------------------