Git commit 99b7e74dae9bfa70190cac96de61c44452bc65ce by Michael Pyne. Committed on 12/08/2013 at 19:45. Pushed by ashark into branch 'docbook_historied_per_file'.
doc: Document the branch-group option. Original commit: d966b820 https://invent.kde.org/sdk/kdesrc-build/-/commit/d966b820a52f045f926653bdf951fbaa6ea84987 M +66 -0 doc/appendix-modules/module-concept.docbook M +64 -3 doc/kdesrc-buildrc/conf-options-table.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/99b7e74dae9bfa70190cac96de61c44452bc65ce diff --git a/doc/appendix-modules/module-concept.docbook b/doc/appendix-modules/module-concept.docbook index b223fe0a..47ec9dc5 100644 --- a/doc/appendix-modules/module-concept.docbook +++ b/doc/appendix-modules/module-concept.docbook @@ -59,4 +59,70 @@ 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> diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook index c7279992..1b9a7701 100644 --- a/doc/kdesrc-buildrc/conf-options-table.docbook +++ b/doc/kdesrc-buildrc/conf-options-table.docbook @@ -80,15 +80,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>
