tutorials: Add workspaces tutorial

This is part of the work towards issue #437

5 files changed, 113 insertions, 2 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 381ab90ad..9a5e98754 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -121,7 +121,8 @@ html devhelp: templates sessions
             $(wildcard source/advanced-features/*.rst) \
 	    $(wildcard source/examples/*.rst) \
 	    $(wildcard source/elements/*.rst) \
-	    $(wildcard source/sources/*.rst)
+	    $(wildcard source/sources/*.rst) \
+	    $(wildcard source/developing/*.rst)
 	@echo
 	@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"
 # Makefile for Sphinx documentation
diff --git a/doc/examples/developing/project.conf b/doc/examples/developing/project.conf
index de266178e..f799881ce 100644
--- a/doc/examples/developing/project.conf
+++ b/doc/examples/developing/project.conf
@@ -1,5 +1,5 @@
 # Unique project name
-name: running-commands
+name: developing 
 
 # Required BuildStream format version
 format-version: 9
diff --git a/doc/source/developing/workspaces.rst b/doc/source/developing/workspaces.rst
new file mode 100644
index 000000000..a545bb661
--- /dev/null
+++ b/doc/source/developing/workspaces.rst
@@ -0,0 +1,98 @@
+
+
+.. _developing_workspaces:
+
+Workspaces
+==========
+
+In this section we will cover the use of BuildStream's workspaces feature when devloping on a 
+BuildStream project.
+.. note::
+
+   This example is distributed with BuildStream
+   in the `doc/examples/developing
+   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/developing>`_
+   subdirectory.
+
+We will start with the project used in the :ref:`running commands <tutorial_running_commands>`
+tutorial. Recall the element hello.bst, which builds the bellow C file:
+
+.. literalinclude:: ../../examples/developing/files/src/hello.c
+   :language: c
+
+Suppose we now want to alter the functionality of the *hello* command. We can
+make changes to the source code of Buildstream elements by making use of
+BuildStream's workspace command.
+
+
+
+Opening a workspace
+-------------------
+First we need to open a workspace, we can do this by running
+
+.. raw:: html
+   :file: ../sessions/developing-workspace-open.html
+
+This command has created the workspace_hello directory in which you can see
+the source for the hello.bst element, i.e. hello.c and the corresponding
+makefile.
+
+
+You can view existing workspaces using
+
+.. raw:: html
+   :file: ../sessions/developing-workspace-list.html
+
+Making code changes
+-------------------
+Let's say we want to alter the message printed when the hello command is run.
+We can open workspace_hello/hello.c and make the following change:
+
+.. literalinclude:: ../../examples/developing/update.patch
+    :language: diff
+
+Now, rebuild the hello.bst element
+
+.. raw:: html
+   :file: ../sessions/developing-build-after-changes.html
+
+Now running the hello command using bst shell:
+
+.. raw:: html
+   :file: ../sessions/developing-shell-after-changes.html
+
+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.
+
+Closing your workspace
+----------------------
+If we want to close the workspace and come back to our changes later, we can
+
+.. raw:: html
+   :file: ../sessions/developing-close-workspace.html
+
+We can then reopen the workspace later using:
+
+.. raw:: html
+   :file: ../sessions/developing-reopen-workspace.html
+
+The --no-checkout option tells BuildStream not to check the source out but to
+instead hard-link to the workspace_hello directory.
+
+Alternatively, if we wish to discard the changes we can use
+
+.. raw:: html
+   :file: ../sessions/developing-reset-workspace.html
+
+This resets the workspace to its original state.
+
+To discard the workspace completely we can do:
+
+.. raw:: html
+   :file: ../sessions/developing-discard-workspace.html
+
+This will close the workspace and completely remove the workspace_hello
+directory.
+
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index 6201b1293..65786e9eb 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -10,6 +10,7 @@ guides and information on user preferences and configuration.
    :maxdepth: 2
 
    using_tutorial
+   using_developing
    using_advanced_features
    using_examples
    using_config
diff --git a/doc/source/using_developing.rst b/doc/source/using_developing.rst
new file mode 100644
index 000000000..03b43f977
--- /dev/null
+++ b/doc/source/using_developing.rst
@@ -0,0 +1,11 @@
+Developing with BuildStream
+===========================
+This is an introduction to the  step by step walkthrough aimed at helping users
+get to grips with the process of developing a project using BuildStream. 
+
+
+.. toctree::
+   :numbered:
+   :maxdepth: 1
+
+   developing/workspaces.rst