Add changelog and upgrading-checklist for #641153

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 53b78b0d349fa4c4707df1b3eaebc8310bfb5631..aa42b5d078c84b822aa89a1b04eeb7b931713432 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -2646,6 +2646,7 @@ Package: libc6
            <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+           <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
          </list>
        </p>
 
@@ -2701,6 +2702,7 @@ Package: libc6
            <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+           <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
          </list>
        </p>
       </sect>
@@ -4607,13 +4609,13 @@ fi
 
        <p>
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
-         <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
-         strictly earlier, earlier or equal, exactly equal, later or
-         equal and strictly later, respectively.  The deprecated
-         forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
-         earlier/later or equal, rather than strictly earlier/later,
-         so they should not appear in new packages (though
-         <prgn>dpkg</prgn> still supports them).
+         <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for strictly
+         earlier, earlier or equal, exactly equal, later or equal and
+         strictly later, respectively.  The deprecated
+         forms <tt>&lt;</tt> and <tt>&gt;</tt> were confusingly used to
+         mean earlier/later or equal, rather than strictly earlier/later,
+         and must not appear in new packages (though <prgn>dpkg</prgn>
+         still supports them with a warning).
        </p>
 
        <p>
@@ -4677,7 +4679,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
        </p>
 
        <p>
-         For binary relationship fields, the architecture restriction
+         For binary relationship fields and the <tt>Built-Using</tt>
+         field, the architecture restriction
          syntax is only supported in the source package control
          file <file>debian/control</file>.  When the corresponding binary
          package control file is generated, the relationship will either
@@ -5401,6 +5404,53 @@ Replaces: mail-transport-agent
          </taglist>
        </p>
       </sect>
+
+      <sect id="built-using">
+       <heading>Additional source packages used to build the binary
+         - <tt>Built-Using</tt>
+       </heading>
+
+       <p>
+         Some binary packages incorporate parts of other packages when built
+         but do not have to depend on those packages.  Examples include
+         linking with static libraries or incorporating source code from
+         another package during the build.  In this case, the source packages
+         of those other packages are a required part of the complete source
+         (the binary package is not reproducible without them).
+       </p>
+
+       <p>
+         A <tt>Built-Using</tt> field must list the corresponding source
+         package for any such binary package incorporated during the build
+         <footnote>
+           <tt>Build-Depends</tt> in the source package is not adequate since
+           it (rightfully) does not document the exact version used in the
+           build.
+         </footnote>,
+         including an "exactly equal" ("=") version relation on the version
+         that was used to build that binary package<footnote>
+           The archive software might reject packages that refer to
+           non-existent sources.
+         </footnote>.
+       </p>
+
+       <p>
+         A package using the source code from the gcc-4.6-source
+         binary package built from the gcc-4.6 source package would
+         have this field in its control file:
+         <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+         </example>
+       </p>
+
+       <p>
+         A package including binaries from grub2 and loadlin would
+         have this field in its control file:
+         <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+         </example>
+       </p>
+      </sect>
     </chapt>
 
 
@@ -7980,9 +8030,10 @@ fname () {
          as its interpreter.  Checking your script
          with <prgn>checkbashisms</prgn> from
          the <package>devscripts</package> package or running your script
-         with <prgn>posh</prgn> may help uncover violations of the above
-         requirements.  If in doubt whether a script complies with these
-         requirements, use <file>/bin/bash</file>.
+         with an alternate shell such as <prgn>posh</prgn> may help
+         uncover violations of the above requirements.  If in doubt
+         whether a script complies with these requirements,
+         use <file>/bin/bash</file>.
        </p>
 
        <p>
@@ -9935,6 +9986,10 @@ END-INFO-DIR-ENTRY
          <file>README.Debian</file> or some other appropriate place.
        </p>
 
+       <p>
+         All copyright files must be encoded in UTF-8.
+       </p>
+
        <sect1 id="copyrightformat">
          <heading>Machine-readable copyright information</heading>