handbook: Add more information about extending Poky

Add more details on using in a team environment and how collections
can be used to manage groups of different kinds of changes

Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>

1 files changed, 92 insertions, 3 deletions

diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index f259d2ef0..fa789d4af 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -26,7 +26,15 @@
         </para>
 
         <para>
-            The simplest way to add a new package is to base it on a similar
+            Before writing a recipe from scratch it is often useful to check
+            someone else hasn't written one already. OpenEmbedded is a good place 
+            to look as it has a wider scope and hence a wider range of packages.
+            Poky aims to be compatible with OpenEmbedded so most recipes should
+            just work in Poky.
+        </para>
+
+        <para>
+            For new packages, the simplest way to add a recipe is to base it on a similar
             pre-existing recipe. There are some examples below of how to add 
             standard types of packages:
         </para>
@@ -556,6 +564,37 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
             </para>
         </section>
 
+        <section id="usingpoky-changes-supplement">
+            <title>Supplementry Metadata Repositories</title>
+
+            <para>
+                Often when developing a project based on Poky there will be components 
+                that are not ready for public consumption for whatever reason. By making
+                use of the collections mechanism and other functionality within Poky, it
+                is possible to have a public repository which is supplemented by a private 
+                one just containing the pieces that need to be kept private. 
+            </para>
+            <para>
+                The usual approach with these is to create a separate git repository called 
+                "meta-prvt-XXX" which is checked out alongside the other meta-* 
+                directories included in Poky. Under this directory there can be several 
+                different directories such as classes, conf and packages which all 
+                function as per the usual Poky directory structure. 
+            </para>
+            <para>
+                If extra meta-* directories are found, Poky will automatically add them 
+                into the BBPATH variable so the conf and class files contained there 
+                are found. If a file called poky-extra-environment is found within the 
+                meta-* directory, this will be sourced as the environment is setup, 
+                allowing certain configuration to be overridden such as the location of the 
+                local.conf.sample file that is used.
+            </para>
+            <para>
+                Note that at present, BBFILES is not automatically changed and this needs 
+                to be adjusted to find files in the packages/ directory. Usually a custom 
+                local.conf.sample file will be used to handle this instead.
+            </para>
+        </section>
 
         <section id='usingpoky-changes-commits'>
             <title>Committing Changes</title>
@@ -564,8 +603,8 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
                 Modifications to Poky are often managed under some kind of source
                 revision control system. The policy for committing to such systems
                 is important as some simple policy can significantly improve 
-                usability. The tips below are based on the policy that OpenedHand 
-                uses for commits to Poky.
+                usability. The tips below are based on the policy followed for the 
+                Poky core.
             </para>
 
             <para>
@@ -622,6 +661,56 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
                 upgradable packages in all cases.
             </para>
         </section>
+        <section id='usingpoky-changes-collaborate'>
+            <title>Using Poky in a Team Environment</title>
+
+            <para>
+                It may not be immediately clear how Poky can work in a team environment, 
+                or scale to a large team of developers. The specifics of any situation
+                will determine the best solution and poky offers immense flexibility in 
+                that aspect but there are some practises that experience has shown to work
+                well.
+            </para>
+
+            <para>
+                The core component of any development effort with Poky is often an 
+                automated build testing framework and image generation process. This 
+                can be used to check that the metadata is buildable, highlight when 
+                commits break the builds and provide up to date images allowing people 
+                to test the end result and use them as a base platform for further 
+                development. Experience shows that buildbot is a good fit for this role 
+                and that it works well to configure it to make two types of build - 
+                incremental builds and 'from scratch'/full builds. The incremental builds 
+                can be tied to a commit hook which triggers them each time a commit is 
+                made to the metadata and are a useful acid test of whether a given commit 
+                breaks the build in some serious way. They catch lots of simple errors 
+                and whilst they won't catch 100% of failures, the tests are fast so 
+                developers can get feedback on their changes quickly. The full builds
+                are builds that build everything from the ground up and test everything. 
+                They usually happen at preset times such as at night when the machine 
+                load isn't high from the incremental builds.
+            </para>
+
+            <para>
+                Most teams have pieces of software undergoing active development. It is of
+                significant benefit to put these under control of a source control system 
+                compatible with Poky such as git or svn. The autobuilder can then be set to 
+                pull the latest revisions of these packages so the latest commits get tested 
+                by the builds allowing any issues to be highlighted quickly. Poky easily
+                supports configurations where there is both a stable known good revision 
+                and a floating revision to test. Poky can also only take changes from specific
+                source control branches giving another way it can be used to track/test only
+                specified changes.
+            </para>
+            <para>
+                Perhaps the hardest part of setting this up is the policy that surrounds 
+                the different source control systems, be them software projects or the Poky 
+                metadata itself. The circumstances will be different in each case but this is
+                one of Poky's advantages - the system itself doesn't force any particular policy
+                unlike a lot of build systems, allowing the best policy to be chosen for the 
+                circumstances.
+            </para>
+        </section>
     </section>
 
     <section id='usingpoky-modifing-packages'>