[website] 05/08: Improve 'Upgrading to a new upstream release' section.

[Bas Couwenberg]

This is an automated email from the git hooks/post-receive script.

sebastic-guest pushed a commit to branch master
in repository website.

commit a55da93342a83daa1e2f86bb319c08fb05d30dee
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date:   Sat Feb 22 02:19:17 2014 +0100

    Improve 'Upgrading to a new upstream release' section.
---
 policy.xml | 53 ++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 13 deletions(-)

diff --git a/policy.xml b/policy.xml
index f7c7a89..726c182 100644
--- a/policy.xml
+++ b/policy.xml
@@ -903,30 +903,36 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder
             Refer to
             <link linkend="git-pbuilder">Setup the build environment</link>
             for details about creating the <command>cowbuilder</command>
-            chroots.
-          </para>
-          <para>
-            ...
+            chroots, and the recommended
+            <link linkend="debian-gbp.conf"><filename>debian/gbp.conf</filename></link>
+            to configure <command>git-buildpackage</command> to use
+            <command>cowbuilder</command> by default.
           </para>
         </sect4>
         <sect4 id="git-new-upstream">
           <title>Upgrading to a new upstream release</title>
           <para>
             <command>git-buildpackage</command>'s command
-            <command>git-import-orig</command> makes it easy to update of the
+            <command>git-import-orig</command> makes it easy to update the
             <literal>upstream</literal> branch using upstream releases
             distributed as a compressed archive, and to merge these changes in
             the <literal>master</literal> branch.
-            Its option <command>--pristine-tar</command>
-            is useful for stabilizing the MD5 sum of the
-            "<filename>orig.tar.gz</filename>" produced when building a source
-            package from the repository alone (not doing so results in archive
-            rejection of package updates).
-            With recent versions of <command>git-buildpackage</command>,
-            it is often unnecessary to rename the freshly downloaded original
-            upstream archive.
           </para>
           <para>
+            The <command>git-import-orig</command>
+            <option>--pristine-tar</option> option is very useful for
+            stabilizing the MD5 sum of the <filename>orig.tar.gz</filename>
+            produced when building a source package from the repository alone
+            (not doing so results in archive rejection of package updates).
+          </para>
+          <tip>
+            <para>
+              With recent versions of <command>git-buildpackage</command>,
+              it is often unnecessary to rename the freshly downloaded original
+              upstream archive.
+            </para>
+          </tip>
+          <para>
             If you do not use <command>git-buildpackage</command>, please use
             <command>pristine-tar</command> anyway to register the compressed
             archives that you upload to Debian as original upstream sources
@@ -941,6 +947,27 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder
 </programlisting>
           </para>
           <para>
+            When the <option>pristine-tar</option> option is not configured in
+            <link linkend="debian-gbp.conf"><filename>debian/gbp.conf</filename></link>
+            you need to explicitly use
+            <command>git-import-orig</command> <option>--pristine-tar</option>.
+          </para>
+          <warning>
+            <para>
+              While it's possible to use the <option>--uscan</option> option
+              to have <command>git-import-orig</command> download the upstream
+              tarball using <command>uscan</command> before importing it,
+              its use is not recommended when the upstream tarball is repacked.
+              There is a bug 
+              (<ulink url="https://bugs.debian.org/635920">#635920</ulink>)
+              that causes <command>git-import-orig</command> to import the
+              unrepacked tarball.
+              This bug is fixed in <literal>jessie</literal>, but
+              <command>git-import-orig</command> in <literal>wheezy</literal>
+              is still affected.
+            </para>
+          </warning>
+          <para>
             ...
           </para>
         </sect4>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/website.git