rewriting of some sentences multiple-tree concept (by Benoit)

master/docs/manual/concepts.rst

@@ -140,41 +140,51 @@ What if an end-product is composed of several components and all these component
 have different repositories? Changes may arrive from different repositories within
 the tree-stable-timer period. Buildbot will not only use the source-trees that
 contain changes but also needs the remaining source-trees to build the complete
-product. The remaining source-trees could be in the 'stable' branches but for
-nightly tests the latest revision of the 'default' branch could also be used.
+product. 
 
-For this reason a :class:`Scheduler` can be configured to base a build on a set
+For this reason a :ref:`Scheduler<Scheduling-Builds>` can be configured to base a build on a set
 of several source-trees that can (partly) be overidden by the specific revisions
 inside the arrived :class:`Change`\s.
 
+
 A single source-tree is identified by its repository, branch and revision. The
 repository is a reference to a place where the sources reside. In projects it is
-possible to have the same sources at different places (for example a local
-repository and one on Github). For this reason an extra identifier 'codebase' is
-used to distinguish different repositories and to treat equal repositories as
-the same.
+possible to have the same sources at different places (for example a collection
+of fork of the same repository). For this reason an extra identifier 'codebase'
+has been introduced to make buildbot categorize all copies of the same source-tree
+as the same. Furthermore, the codebase_ allow you to uniquely identify a *part* of
+your project.
 
 A complete multiple repository configuration consists of:
 
     - a *codebase generator*
 
-        Every relevant change arriving from a VC must contain a codebase. Because VC's
-        do not supply a codebase this has to be done by a so called
-        :bb:cfg:`codebaseGenerator` that is defined in the configuration.
+        Every relevant change arriving from a VC must contain a codebase.
+        Because VC's do not supply a codebase this has to be done by a so
+        called :bb:cfg:`codebaseGenerator` that is defined in the
+        configuration.
 
     - some *schedulers*
 
-        The :bb:cfg:`scheduler<schedulers>` is configured with a set of codebases.
-        These codebases represent the set of required repositories. For each
-        codebase a default repository, a default branch, and a default revision are supplied to retrieve the source-trees that are not in the arrived changes.
+        The :bb:cfg:`scheduler<schedulers>` has to be configured with a set of all
+        required ``codebases`` to build a product. These codebases indicate the set of
+        required source-trees. In order for the scheduler to be able to produce a
+        complete set for each build, each given codebase will be supplied a default
+        repository, branch, and revision. Those ones will be used for the codebases
+        where no changes arrived.
 
     - multiple *source steps*
 
-        A :ref:`Builder` contains a :ref:`source step<Source-Checkout>` for
-        each codebase. Each of the sourcesteps has a codebase attribute. With this
-        attribute the source step can ask the :class:`Build` object for the
-        correct repository, branch and revision data. The information comes from
-        the arrived changes or from the scheduler's default values.
+        A :ref:`Builder` has to contains a :ref:`source step<Source-Checkout>` for
+        each needed source-tree. Each of the source steps has a ``codebase`` attribute
+        which is used to retrieve the corresponding repository, branch and revision
+        data. This information comes from the arrived changes or from the
+        scheduler's configured default values.
+
+.. warning::
+
+    Defining a :bb:cfg:`codebaseGenerator` that returns non empty (not
+    ``''``) codebases, change the behavior of all the schedulers.
 
 .. _How-Different-VC-Systems-Specify-Sources: