Support defaulting to stable branches from proj.k.o.

Valery Yundin has kindly submitted a patch (including documentation!)
resurrecting the old "use-stable-kde" option to allow for defaulting
kde-projects modules to the stable branch (if defined for that module).

This should track with changes to the stable branch as defined, so it
would be a good way to track the "not quite bleeding-edge" of
development.

A hearty thanks to Valery for making up a patch and then adapting it to
make use of the old use-stable-kde option.

BUG:297357
FIXED-IN:1.15

doc/index.docbook

@@ -384,6 +384,19 @@ The default settings should actually already be appropriate to perform a
 &kde; build. Some settings that you may wish to alter include:
 
 <itemizedlist>
+<listitem><para><link linkend="conf-use-stable-kde">use-stable-kde</link> to
+change the default version of &kde; modules to build. By default &kdesrc-build;
+will build the trunk version of &kde;. If you want to build
+the latest stable release of &kde; instead of using your distribution packages
+you would set this option to <replaceable>true</replaceable>.
+</para>
+
+<tip><para>Note that this option relies on information available from the
+&kde; project database, so this feature only works for these modules.
+See also <xref linkend="kde-projects-module-sets"/>.
+</para></tip>
+</listitem>
+
 <listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the
 destination directory that &kde; is installed to. This defaults to
 <filename class="directory">~/kde</filename>, which is a single-user installation.</para></listitem>
@@ -2154,13 +2167,26 @@ system.
 </entry>
 </row>
 
-<row>
+<row id="conf-use-stable-kde">
 <entry>use-stable-kde</entry>
-<entry></entry>
-<entry><para>
-This option was removed in version 1.10, which limits support to KDE 4,
-removing the effect of this option.
+<entry>Can't be overridden</entry>
+<entry><para>By default, &kdesrc-build; will build the main line of &kde;
+development (trunk or master branch). You can use the &branch; option globally
+or for a module in order to switch to a stable release. However, this is not
+convenient as a lot of branch options would have to be added to the
+configuration file and kept up to date when the next stable version is
+released.</para>
+
+<para>So, if you set this option to <replaceable>true</replaceable>,
+&kdesrc-build; will (for a given module) automatically download the version of
+that module which is marked as stable in kde_projects.xml.</para>
+
+<para>This option can only be set globally, but you can still use the &branch;
+or &tag; options for a module to override this option.
+This way you can easily choose to download current stable &kde; version by default
+while still choosing the current development version of specific modules.
 </para>
+
 </entry>
 </row>
 

kdesrc-build

@@ -1339,25 +1339,34 @@ EOF
                 'name' => $nameStack[-1],
                 'active' => 'false',
                 'tarball' => '',
+                'branch:stable' => '',
             }; # Repo/Active/tarball to be added by char handler.
         }
 
+        # Currently we only pull data while under a <repo> tag, so bail early if
+        # we're not doing this to simplify later logic.
+        return unless $inRepo;
+
         # Character data is integrated by the char handler. To avoid having it
         # dump all willy-nilly into our dict, we leave a flag for what the
         # resultant key should be.
-        if ($element eq 'active' && $inRepo) {
+        if ($element eq 'active') {
             $curRepository->{'needs'} = 'active';
 
             # Unset our default value since one is present in the XML
             $curRepository->{'active'} = '';
         }
-
-        if ($element eq 'url' && $inRepo && $attrs{'protocol'} eq 'git') {
-            $curRepository->{'needs'} = 'repo';
+        # For git repos we want to retain the repository data and any snapshot
+        # tarballs available.
+        elsif ($element eq 'url' && $attrs{'protocol'} eq 'git') {
+            $curRepository->{'needs'} =
+                #                    this proto | needs this attr set
+                $attrs{'protocol'} eq 'git'     ? 'repo'    :
+                $attrs{'protocol'} eq 'tarball' ? 'tarball' : undef;
         }
-
-        if ($element eq 'url' && $inRepo && $attrs{'protocol'} eq 'tarball') {
-            $curRepository->{'needs'} = 'tarball';
+        # i18n data gives us the defined stable and trunk branches.
+        elsif ($element eq 'branch' && $attrs{'i18n'} && $attrs{'i18n'} eq 'stable') {
+            $curRepository->{'needs'} = 'branch:stable';
         }
     }
 
@@ -1537,6 +1546,8 @@ EOF
         "tag"                  => "",
         "use-clean-install"    => 0,
         "use-idle-io-priority" => 0,
+        # Controls whether to build "stable" branches instead of "master"
+        "use-stable-kde"       => 0,
     );
     # }}} 1
 
@@ -5248,7 +5259,14 @@ sub get_git_branch
     my $module = assert_isa(shift, 'Module');
     my $branch = $module->getOption('branch');
 
-    $branch = 'master' unless $branch;
+    if (!$branch && $module->getOption('use-stable-kde')) {
+        my $stable = $module->getOption('#branch:stable');
+        if ($stable && $stable ne 'none') {
+            $branch = $stable;
+        }
+    }
+
+    $branch ||= 'master'; # If no branch, use 'master'
     return $branch;
 }
 
@@ -5688,7 +5706,7 @@ sub git_update_module
 
     p_chdir($srcdir);
 
-    note ("Updating g[$module]");
+    note ("Updating g[$module] (to branch b[$branch])");
     my $start_commit = git_commit_id($module);
 
     # Search for an existing remote name first. If none, add our alias.
@@ -6553,6 +6571,7 @@ sub expandXMLModules
             $_->setModuleSet($moduleSet->moduleSet());
             $_->setOption('repository', $repo);
             $_->setOption('#xml-full-path', $result->{'fullName'});
+            $_->setOption('#branch:stable', $result->{'branch:stable'});
 
             my $tarball = $result->{'tarball'};
             $_->setOption('#snapshot-tarball', $tarball) if $tarball;