[kde-doc-english] [kdesrc-build] doc: doc: Document the branch-group option.

[Michael Pyne]

Git commit d966b820a52f045f926653bdf951fbaa6ea84987 by Michael Pyne.
Committed on 12/08/2013 at 19:45.
Pushed by mpyne into branch 'master'.

doc: Document the branch-group option.

M  +130  -3    doc/index.docbook

http://commits.kde.org/kdesrc-build/d966b820a52f045f926653bdf951fbaa6ea84987

diff --git a/doc/index.docbook b/doc/index.docbook
index efa0882..9205077 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -1541,15 +1541,76 @@ may use the tilde (~) for any paths you add using this option.</para>
 <entry>branch</entry>
 <entry>Module setting overrides global</entry>
 <entry><para>Set this option to checkout from a branch of &kde; instead of the
-default of <replaceable>trunk</replaceable>, where &kde; development occurs.
+default of <replaceable>master</replaceable> (for &git; modules) or
+<replaceable>trunk</replaceable> (for &subversion;), where &kde; development
+occurs.</para>
+
+<para>
 For instance, to checkout &kde; 4.6 branch, you would set this option to
 <replaceable>4.6</replaceable>.</para>
+
 <para>If &kdesrc-build; fails to properly download a branch with this option, you
 may have to manually specify the &url; to download from using the <link
 linkend="conf-module-base-path">module-base-path</link> or <link
 linkend="conf-override-url">override-url</link> options.</para>
-<para>Note: This option also works with source modules that use
-&git; instead of &subversion;.</para>
+
+<note><para>For most &kde; modules you probably wish to use the <link
+linkend="conf-branch-group">branch-group</link> option instead and use this
+option for case-by-case exceptions.</para></note>
+
+</entry>
+</row>
+
+<row id="conf-branch-group">
+<entry>branch-group</entry>
+<entry>Module setting overrides global</entry>
+<entry>
+
+<para>Set this option to a general group from which you want modules to be
+chosen.</para>
+
+<para>For supported &git; module types, &kdesrc-build; will determine the
+actual branch to use automatically based on rules encoded by the &kde;
+developers (these rules may be viewed in the
+<literal>kde-build-metadata</literal> source repository in your source
+directory). After a branch is determined that branch is used as if you had
+specified it yourself using the <link linkend="conf-branch">branch</link>
+option.
+</para>
+
+<para>This is useful if you're just trying to maintain up-to-date on some
+normal development track without having to pay attention to all the branch name
+changes.</para>
+
+<para>The current branch groups (as of 2013-08-11) are:</para>
+
+<itemizedlist>
+
+<listitem><para><literal>stable-qt4</literal>, for tracking bugfixes to the
+&Qt; 4-based &kde; libraries and applications.</para></listitem>
+
+<listitem><para><literal>latest-qt4</literal>, for tracking development and new
+features for the &Qt; 4-based &kde; libraries and
+applications.</para></listitem>
+
+<listitem><para><literal>kf5-qt5</literal>, for tracking
+<quote>bleeding-edge</quote> development for the upcoming &Qt; 5-based &kde;
+Frameworks 5, &plasma; Workspace 2, &etc;</para></listitem>
+
+</itemizedlist>
+
+<para>Note that if you <emphasis>do</emphasis> choose a
+<literal>branch</literal> yourself, that it will override this setting. The
+same is true of other specific branch selection options such as <link
+linkend="conf-tag">tag</link>.</para>
+
+<para>This option was added in &kdesrc-build; 1.16-pre2.</para>
+
+<note><para>This option only applies to <literal>kde-projects</literal> &git;
+modules (the common case).  See also <xref
+linkend="kde-projects-module-sets"/>.
+</para></note>
+
 </entry>
 </row>
 
@@ -3938,6 +3999,72 @@ in this case) empty if you like. This <option>repository</option> setting tells
 automatically include any Git modules that are grouped under the modules you
 list (in the KDE Project database).</para>
 </sect2>
+
+<sect2 id="module-branch-groups">
+<title>Module <quote>branch groups</quote></title>
+
+<para>Taking the concept of a <link linkend="module-groups">group of
+modules</link> further, the &kde; developers eventually found that
+synchronizing the names of the Git branches across a large number of
+repositories was getting difficult, especially during the development push for
+the new &kde; Frameworks for &Qt; 5.
+</para>
+
+<para>So the concept of <quote>branch groups</quote> was developed, to allow
+users and developers to select one of only a few groups, and allow the script
+to automatically select the appropriate Git branch.
+</para>
+
+<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the
+<link linkend="conf-branch-group">branch-group</link> option.
+</para>
+
+<example id="ex-branch-group">
+<title>Example of using branch-group</title>
+
+<para>branch-group can be used in the configuration file as follows:
+</para>
+
+<programlisting>
+global
+    # Select KDE Frameworks 5 and other Qt5-based apps
+    <option>branch-group</option> <replaceable>kf5-qt5</replaceable>
+
+    # Other global options here ...
+end global
+
+module-set
+    # branch-group only works for kde-projects
+    <option>repository</option> kde-projects
+
+    # branch-group is inherited from the one set globally, but could
+    # specified here.
+
+    <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable>
+end module-set
+
+# kdelibs's branch will be "frameworks"
+# kde-workspace's branch will be "master" (as of August 2013)
+</programlisting>
+
+<para>In this case the same <literal>branch-group</literal> gives different
+branch names for each Git module.
+</para>
+</example>
+
+<para>This feature requires some data maintained by the &kde; developers in a Git
+repository named <literal>kde-build-metadata</literal>, however this module
+will be included automatically by &kdesrc-build; (though you may see it appear
+in the script output).
+</para>
+
+<tip><para>&kde; modules that do not have a set branch name for the branch
+group you choose will default to an appropriate branch name, as if you had not
+specified <literal>branch-group</literal> at all.
+</para></tip>
+
+</sect2>
+
 </sect1>
 </appendix>