1 files changed, 117 insertions, 0 deletions
diff --git a/doc/source/tutorial/first-project.rst b/doc/source/tutorial/first-project.rst
new file mode 100644
index 000000000..9112350f0
--- /dev/null
+++ b/doc/source/tutorial/first-project.rst
@@ -0,0 +1,117 @@
+
+Your first project
+==================
+To get a feel for the basics, we'll start with the most basic BuildStream project we
+could think of.
+
+.. note::
+
+   This example is distributed with BuildStream
+   in the `doc/examples/first-project
+   <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/first-project>`_
+   subdirectory.
+
+
+Creating the project
+--------------------
+First, lets create the project itself using the convenience :ref:`bst init <invoking_init>`
+command to create a little project structure:
+
+.. raw:: html
+   :file: ../sessions/first-project-init.html
+
+This will give you a :ref:`project.conf <projectconf>` which will look like this:
+
+.. literalinclude:: ../../examples/first-project/project.conf
+   :language: yaml
+
+The :ref:`project.conf <projectconf>` is a central point of configuration
+for your BuildStream project.
+
+
+Add some content
+----------------
+BuildStream processes directory trees as input and output,
+so let's just create a ``hello.world`` file for the project
+to have.
+
+.. raw:: html
+   :file: ../sessions/first-project-touch.html
+
+
+Declare the element
+-------------------
+Here we're going to declare a simple :mod:`import <elements.import>` element
+which will import the ``hello.world`` file we've created in the previous step.
+
+Create ``elements/hello.bst`` with the following content:
+
+.. literalinclude:: ../../examples/first-project/elements/hello.bst
+   :language: yaml
+
+
+The source
+~~~~~~~~~~
+The :mod:`local <sources.local>` source used by the ``hello.bst`` element,
+can be used to access files or directories which are stored in the same repository
+as your BuildStream project. The ``hello.bst`` element uses the :mod:`local <sources.local>`
+source to stage our local ``hello.world`` file.
+
+
+The element
+~~~~~~~~~~~
+The :mod:`import <elements.import>` element can be used to simply add content
+directly to the output artifacts. In this case, it simply takes the ``hello.world`` file
+provided by it's source and stages it directly to the artifact output root.
+
+.. tip::
+
+   In this example so far we've used two plugins, the :mod:`local <sources.local>`
+   source and the :mod:`import <elements.import>` element.
+
+   You can always browse the documentation for all plugins in
+   the :ref:`plugins section <plugins>` of the manual.
+
+
+Build the element
+-----------------
+In order to carry out the activities of the :mod:`import <elements.import>` element
+we've declared, we're going to have to ask BuildStream to *build*.
+
+This process will collect all of the sources required for the specified ``hello.bst``
+and get the backing :mod:`import <elements.import>` element to generate an *artifact*
+for us.
+
+.. raw:: html
+   :file: ../sessions/first-project-build.html
+
+Now the artifact is ready.
+
+Using ``bst show``, we can observe that the artifact's state, which was reported
+as ``buildable`` in the ``bst build`` command above, has now changed to ``cached``:
+
+.. raw:: html
+   :file: ../sessions/first-project-show.html
+
+
+Observe the output
+------------------
+Now that we've finished building, we can checkout the output of the
+artifact we've created:
+
+.. raw:: html
+   :file: ../sessions/first-project-checkout.html
+
+And observe that the file we expect is there:
+
+.. raw:: html
+   :file: ../sessions/first-project-ls.html
+
+
+Summary
+-------
+In this section we've created our first BuildStream project from
+scratch, but it doesnt do much.
+
+We've observed the general structure of a BuildStream project,
+and we've run our first build.