update the README with example project layout

Signed-off-by: Alfredo Deza <alfredo@deza.pe>

diff --git a/README.rst b/README.rst
index e62b405c7009eae55db718b19b6e865e878639df..35ffb4e05ae3d66b50f60012142e5560a863b0c9 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -21,6 +21,11 @@ This script should have all the rules and requirements for generating the
 Jenkins configurations needed from the YAML files to create/update the jenkins
 job.
 
+deprecation
+-----------
+Any script in the top level of this repo is now deprecated and should be moved
+to follow the structure of the Jenkins Job Builder project.
+
 enforcement
 -----------
 The rules and structure for the builds are *strictly* enforced. If the
@@ -28,10 +33,85 @@ convention is not followed, the builds will not work.
 
 Changing Jenkins jobs in Jenkins is **strongly** discouraged.
 
-To learn more about the structure and how to order a project build see the
-`Amauta <https://github.com/alfredodeza/amauta>`_ project documentation.
+By default, this is how a directory tree would look like for a build for
+a project called ``foo`` that uses every choice available::
 
-deprecation
------------
-Any script in the top level of this repo is now deprecated and should be moved
-to follow the structure of the Jenkins Job Builder project.
+    foo
+    ├── config
+    |   ├── config
+    |   └── definitions
+    |       └── foo.yml
+    |   ├── setup
+    |   ├── post
+    |   └── pre
+    ├── setup
+    |   ├── setup
+    |   ├── post
+    |   └── pre
+    ├── build
+    │   ├── build
+    │   ├── post
+    │   └── pre
+    ├── package
+    │   ├── package
+    │   ├── post
+    │   └── pre
+    └── deploy
+       ├── deploy
+       ├── post
+       └── pre
+
+The structure consists of four steps (shown in the order they would get
+executed) with the files available for finer control of each step and with a
+config directory where the configuration for creating the job in jenkins would
+live.
+
+``pre`` and ``post`` are obvious, while the script name that has the same name
+as the directory will get called in between (after ``pre`` and before ``post``).
+
+Nothing is required with the structure. As long as the convention of file names
+and order, execution will follow the order with whatever exists.
+
+If only the ``setup`` directory is available with a single ``setup`` file, that
+is the only one thing that will get executed.
+
+platform-specific
+-----------------
+Sometimes, the process needs to do something specific depending on the
+distribution, version, release, or architecture. For example installing
+a specific package that is only available on CentOS 5, and not in CentOS 4.
+
+All steps (setup, build, package, and deploy) can define scripts to be run
+whenever any of the distribution metadata matches.
+
+To help in ordering the execution, the directory structure needs to change
+a bit to accomodate for metadata-specific calls. Only ``pre`` and ``post`` are
+allowed to have this mixed behavior (either script or directory/script).
+
+In those directories, the upper most level can accept files that match certain
+metadata information, like distribution name and architecture. If the script
+name matches in a given distro it will get executed.
+
+distribution name (e.g. ``centos`` or ``ubuntu``), architecture (e.g. ``i386``
+or ``x86_64``, or package manager (as in ``yum`` or ``apt``).
+
+Below is an example of having three scripts for ``centos`` that at any given
+time (when there is a match) only two of them will get executed: ``all`` and
+either ``5`` or ``6``.
+
+``all`` is a helper that will get executed always for all ``centos`` distro
+versions and combinations::
+
+    foo/setup
+    ├── post
+    │   └── post
+    ├── pre
+    │   ├── centos
+    │   │   ├── 5
+    │   │   ├── 6
+    │   │   └── all
+    │   └── pre
+    └── setup
+
+Because we made ``foo/setup/pre`` a directory, we now define the actual ``pre``
+script (if needed) inside the ``pre`` directory with ``pre`` as the name.