upgrading-checklist.xml

   1 <?xml version='1.0' encoding='utf-8'?>
   2 <!-- -*- DocBook -*- -->
   3 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   5 ]>
   6
   7 <appendix id="upgrading-checklist">
   8   <title>Upgrading checklist</title>
   9
  10   <section id="about">
  11     <title>About the checklist</title>
  12
  13     <para>
  14       The checklist below has been created to simplify the upgrading
  15       process of old packages.  This list is not official or normative.
  16       It only provides an indication of what has changed and whether you
  17       are likely to need to make changes to your package in light of this.
  18       If you have doubts about a certain topic, if you need more details,
  19       or if you think some other package does not comply with policy,
  20       please refer to the Policy Manual itself.
  21     </para>
  22     <para>
  23       All of the changes from version 3.0.0 onwards indicate which section
  24       of the Policy Manual discusses the issue.  The section numbering
  25       should still be accurate for changes back to the 2.5.0 release.
  26       Before that point, the sections listed here probably no longer
  27       correspond to sections in the modern Policy Manual.
  28     </para>
  29     <para>
  30       Here is how the check list works: Check which policy version your
  31       package was checked against last (indicated in the
  32       <literal>Standards-Version</literal> field of the source package).
  33       Then move upwards until the top and check which of the items on the
  34       list might concern your package.  Note which sections of policy
  35       discuss this, and then check out the Policy Manual for details.
  36       Once you've made all necessary changes to match the current rules,
  37       update the value of <literal>Standards-Version</literal> to the
  38       current Policy Manual version.
  39     </para>
  40     <para>
  41       The sections in this checklist match the values for the
  42       <literal>Standards-Version</literal> control field in omitting the
  43       minor patch version, except in the two anomalous historical cases
  44       where normative requirements were changed in a minor patch release.
  45     </para>
  46   </section>
  47
  48   <section id="s-4.0.2">
  49     <title>Version 4.0.2</title>
  50
  51     <para>
  52       Unreleased.
  53     </para>
  54
  55     <variablelist>
  56       <varlistentry>
  57         <term>4.11</term>
  58         <listitem>
  59           <para>
  60             If upstream provides OpenPGP signatures, including the
  61             upstream signing key as
  62             <filename>debian/upstream/signing-key.asc</filename> in the
  63             source package and using the
  64             <literal>pgpsignurlmangle</literal> option in
  65             <filename>debian/watch</filename> configuration to indicate
  66             how to find the upstream signature for new releases is
  67             recommended.
  68           </para>
  69         </listitem>
  70       </varlistentry>
  71     </variablelist>
  72   </section>
  73
  74   <section id="s-4.0.1">
  75     <title>Version 4.0.1</title>
  76
  77     <para>
  78       Released August, 2017.
  79     </para>
  80
  81     <variablelist>
  82       <varlistentry>
  83         <term>2.5</term>
  84         <listitem>
  85           <para>
  86             Priorities are now used only for controlling which packages
  87             are part of a minimal or standard Debian installation and
  88             should be selected based on functionality provided directly to
  89             users (so nearly all shared libraries should have a priority
  90             of <literal>optional</literal>).  Packages may now depend on
  91             packages with a lower priority.
  92           </para>
  93           <para>
  94             The <literal>extra</literal> priority has been deprecated and
  95             should be treated as equivalent to
  96             <literal>optional</literal>.  All <literal>extra</literal>
  97             priorities should be changed to <literal>optional</literal>.
  98             Packages with a priority of <literal>optional</literal> may
  99             conflict with each other (but packages that both have a
 100             priority of <literal>standard</literal> or higher still may
 101             not conflict).
 102           </para>
 103         </listitem>
 104       </varlistentry>
 105       <varlistentry>
 106         <term>5.6.30</term>
 107         <listitem>
 108           <para>
 109             New section documenting the <literal>Testsuite</literal> field in
 110             Debian source control files.
 111           </para>
 112         </listitem>
 113       </varlistentry>
 114       <varlistentry>
 115         <term>8.1.1</term>
 116         <listitem>
 117           <para>
 118             Shared libraries must now invoke
 119             <command>ldconfig</command> by means of triggers, instead
 120             of maintscripts.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term>9.3.3</term>
 126         <listitem>
 127           <para>
 128             Packages are recommended to use debhelper tools instead of
 129             invoking <command>update-rc.d</command> and
 130             <command>invoke-rc.d</command> directly.
 131           </para>
 132         </listitem>
 133       </varlistentry>
 134       <varlistentry>
 135         <term>9.3.3</term>
 136         <listitem>
 137           <para>
 138             Policy's description of how the local system administrator
 139             may modify the runlevels at which a daemon is started and
 140             stopped, and how init scripts may depend on other init
 141             scripts, have been removed.  These are now handled by LSB
 142             headers.
 143           </para>
 144         </listitem>
 145       </varlistentry>
 146       <varlistentry>
 147         <term>9.4</term>
 148         <listitem>
 149           <para>
 150             Policy's specification of the console messages that should
 151             be emitted by <literal>init.d</literal> scripts has been
 152             removed.  This is now defined by LSB, for sysvinit, and is
 153             not expected to be followed by other init systems.
 154           </para>
 155         </listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term>9.6</term>
 159         <listitem>
 160           <para>
 161             Packages installing a Free Desktop entry must not also
 162             install a Debian menu system entry.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry>
 167         <term>9.9</term>
 168         <listitem>
 169           <para>
 170             The prohibition against depending on environment variables for
 171             reasonable defaults is only for programs on the system PATH and
 172             only for custom environment variable settings (not, say, a
 173             sane PATH).
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177     </variablelist>
 178   </section>
 179
 180   <section id="s-4.0.0">
 181     <title>Version 4.0.0</title>
 182
 183     <para>
 184       Released May, 2017.
 185     </para>
 186
 187     <variablelist>
 188       <varlistentry>
 189         <term>4.3</term>
 190         <listitem>
 191           <para>
 192             <command>config.sub</command> and
 193             <command>config.guess</command> should be updated at build
 194             time or replaced with the versions from <systemitem
 195             role="package">autotools-dev</systemitem>.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199       <varlistentry>
 200         <term>4.9</term>
 201         <listitem>
 202           <para>
 203             New <literal>TARGET</literal> set of
 204             <command>dpkg-architecture</command> variables and new
 205             <literal>DEB_*_ARCH_BITS</literal> and
 206             <literal>DEB_*_ARCH_ENDIAN</literal> variables.
 207           </para>
 208         </listitem>
 209       </varlistentry>
 210       <varlistentry>
 211         <term>4.9.1</term>
 212         <listitem>
 213           <para>
 214             New <literal>DEB_BUILD_OPTIONS</literal> tag,
 215             <literal>nodoc</literal>, which says to suppress documentation
 216             generation (but continue to build all binary packages, even
 217             documentation packages, just let them be mostly empty).
 218           </para>
 219         </listitem>
 220       </varlistentry>
 221       <varlistentry>
 222         <term>5.2</term>
 223         <listitem>
 224           <para>
 225             Automatically-generated debug packages do not need to have a
 226             corresponding paragraph in
 227             <filename>debian/control</filename>.  (This is existing
 228             practice; this Policy update is just clearer about it.)
 229           </para>
 230         </listitem>
 231       </varlistentry>
 232       <varlistentry>
 233         <term>5.6.12</term>
 234         <listitem>
 235           <para>
 236             Colons are not permitted in upstream version numbers.
 237           </para>
 238         </listitem>
 239       </varlistentry>
 240       <varlistentry>
 241         <term>7.7</term>
 242         <listitem>
 243           <para>
 244             New <literal>Build-Depends-Arch</literal> and
 245             <literal>Build-Conflicts-Arch</literal> fields are now
 246             supported.
 247           </para>
 248         </listitem>
 249       </varlistentry>
 250       <varlistentry>
 251         <term>8.4</term>
 252         <listitem>
 253           <para>
 254             The recommended package name for shared library development
 255             files is now <replaceable>libraryname</replaceable>-dev or
 256             <replaceable>libraryname</replaceable><replaceable>apiversion</replaceable>-dev,
 257             not
 258             <replaceable>libraryname</replaceable><replaceable>soversion</replaceable>-dev.
 259           </para>
 260         </listitem>
 261       </varlistentry>
 262       <varlistentry>
 263         <term>9.1.1</term>
 264         <listitem>
 265           <para>
 266             The stable release of Debian supports
 267             <filename>/run</filename>, so packages may now assume that it
 268             exists and do not need any special dependency on a version of
 269             initscripts.
 270           </para>
 271         </listitem>
 272       </varlistentry>
 273       <varlistentry>
 274         <term>9.3.2</term>
 275         <listitem>
 276           <para>
 277             New optional <literal>try-restart</literal> standard init
 278             script argument, which (if supported) should restart the
 279             service if it is already running and otherwise just report
 280             success.
 281           </para>
 282         </listitem>
 283       </varlistentry>
 284       <varlistentry>
 285         <term>9.3.2</term>
 286         <listitem>
 287           <para>
 288             Support for the <literal>status</literal> init script argument
 289             is recommended.
 290           </para>
 291         </listitem>
 292       </varlistentry>
 293       <varlistentry>
 294         <term>9.3.3.2</term>
 295         <listitem>
 296           <para>
 297             Packages must not call <filename>/etc/init.d</filename>
 298             scripts directly even as a fallback, and instead must always
 299             use <command>invoke-rc.d</command> (which is essential and
 300             shouldn't require any conditional).
 301           </para>
 302         </listitem>
 303       </varlistentry>
 304       <varlistentry>
 305         <term>9.11.1</term>
 306         <listitem>
 307           <para>
 308             Instructions for <command>upstart</command> integration
 309             removed since <command>upstart</command> is no longer
 310             maintained in Debian.
 311           </para>
 312         </listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term>10.1</term>
 316         <listitem>
 317           <para>
 318             Packages may not install files in both
 319             <filename>/<replaceable>path</replaceable></filename> and
 320             <filename>/usr/<replaceable>path</replaceable></filename>, and
 321             must manage any backward-compatibility symlinks so that they
 322             don't break if
 323             <filename>/<replaceable>path</replaceable></filename> and
 324             <filename>/usr/<replaceable>path</replaceable></filename> are
 325             the same directory.
 326           </para>
 327         </listitem>
 328       </varlistentry>
 329       <varlistentry>
 330         <term>10.6</term>
 331         <listitem>
 332           <para>
 333             Packages should assume device files in
 334             <filename>/dev</filename> are dynamically managed and don't
 335             have to be created by the package.  Packages other than those
 336             whose purpose is to manage <filename>/dev</filename> must not
 337             create or remove files there when a dynamic management
 338             facility is in use.  Named pipes and device files outside of
 339             <filename>/dev</filename> should normally be created on demand
 340             via init scripts, systemd units, or similar mechanisms, but
 341             may be created and removed in maintainer scripts if they must
 342             be created during package installation.
 343           </para>
 344         </listitem>
 345       </varlistentry>
 346       <varlistentry>
 347         <term>10.9</term>
 348         <listitem>
 349           <para>
 350             Checking with the base-passwd maintainer is no longer required
 351             (or desirable) when creating a new dynamic user or group in a
 352             package.
 353           </para>
 354         </listitem>
 355       </varlistentry>
 356       <varlistentry>
 357         <term>12.3</term>
 358         <listitem>
 359           <para>
 360             Dependencies on *-doc packages should be at most Recommends
 361             (Suggests if they only include documentation in supplemental
 362             formats).
 363           </para>
 364         </listitem>
 365       </varlistentry>
 366       <varlistentry>
 367         <term>12.5</term>
 368         <listitem>
 369           <para>
 370             The Mozilla Public License 1.1 and 2.0 (MPL-1.1 and MPL-2.0)
 371             are now included in
 372             <filename>/usr/share/common-licenses</filename> and do not
 373             need to be copied verbatim in the package
 374             <filename>copyright</filename> file.
 375           </para>
 376         </listitem>
 377       </varlistentry>
 378       <varlistentry>
 379         <term>copyright-format</term>
 380         <listitem>
 381           <para>
 382             The <literal>https</literal> form of the copyright-format URL
 383             is now allowed and preferred in the <literal>Format</literal>
 384             field.
 385           </para>
 386         </listitem>
 387       </varlistentry>
 388       <varlistentry>
 389         <term>perl</term>
 390         <listitem>
 391           <para>
 392             The Perl search path now includes multiarch directories.  The
 393             vendor directory for architecture-specific modules is now
 394             versioned to support multiarch.
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398       <varlistentry>
 399         <term>virtual</term>
 400         <listitem>
 401           <para>
 402             New <literal>adventure</literal> virtual package for
 403             implementations of the classic Colossal Cave Adventure game.
 404           </para>
 405         </listitem>
 406       </varlistentry>
 407       <varlistentry>
 408         <term>virtual</term>
 409         <listitem>
 410           <para>
 411             New <literal>httpd-wsgi3</literal> virtual package for Python
 412             3 WSGI-capable HTTP servers.  The existing
 413             <literal>httpd-wsgi</literal> virtual package is for Python 2
 414             WSGI-capable HTTP servers.
 415           </para>
 416         </listitem>
 417       </varlistentry>
 418       <varlistentry>
 419         <term>virtual</term>
 420         <listitem>
 421           <para>
 422             New <literal>virtual-mysql-client</literal>,
 423             <literal>virtual-mysql-client-core</literal>,
 424             <literal>virtual-mysql-server</literal>,
 425             <literal>virtual-mysql-server-core</literal>, and
 426             <literal>virtual-mysql-testsuite</literal> virtual packages
 427             for MySQL-compatible software.
 428           </para>
 429         </listitem>
 430       </varlistentry>
 431     </variablelist>
 432   </section>
 433
 434   <section id="s-3.9.8.0">
 435     <title>Version 3.9.8</title>
 436
 437     <para>
 438       Released April, 2016.
 439     </para>
 440
 441     <variablelist>
 442       <varlistentry>
 443         <term>9.6</term>
 444         <listitem>
 445           <para>
 446             The menu system is deprecated in favor of the FreeDesktop menu
 447             standard.  New requirements set for FreeDesktop menu entries.
 448           </para>
 449         </listitem>
 450       </varlistentry>
 451       <varlistentry>
 452         <term>9.7</term>
 453         <listitem>
 454           <para>
 455             New instructions for registering media type handlers with the
 456             FreeDesktop system, which automatically synchronizes with
 457             mailcap and therefore replaces mailcap registration for
 458             packages using desktop entries.
 459           </para>
 460         </listitem>
 461       </varlistentry>
 462     </variablelist>
 463   </section>
 464
 465   <section id="s-3.9.7.0">
 466     <title>Version 3.9.7</title>
 467
 468     <para>
 469       Released February, 2016.
 470     </para>
 471
 472     <variablelist>
 473       <varlistentry>
 474         <term>10.5</term>
 475         <listitem>
 476           <para>
 477             Symbolic links must not traverse above the root directory.
 478           </para>
 479         </listitem>
 480       </varlistentry>
 481       <varlistentry>
 482         <term>9.2.2</term>
 483         <listitem>
 484           <para>
 485             32bit UIDs in the range 65536-4294967293 are reserved for
 486             dynamically allocated user accounts.
 487           </para>
 488         </listitem>
 489       </varlistentry>
 490       <varlistentry>
 491         <term>5.1</term>
 492         <listitem>
 493           <para>
 494             Empty field values in control files are only permitted in the
 495             <filename>debian/control</filename> file of a source package.
 496           </para>
 497         </listitem>
 498       </varlistentry>
 499       <varlistentry>
 500         <term>4.9</term>
 501         <listitem>
 502           <para>
 503             <filename>debian/rules</filename>: required targets must not
 504             attempt network access.
 505           </para>
 506         </listitem>
 507       </varlistentry>
 508       <varlistentry>
 509         <term>12.3</term>
 510         <listitem>
 511           <para>
 512             recommend to ship additional documentation for package
 513             <command>pkg</command> in a separate package
 514             <command>pkg-doc</command> and install it into
 515             <filename>/usr/share/doc/pkg</filename>.
 516           </para>
 517         </listitem>
 518       </varlistentry>
 519     </variablelist>
 520   </section>
 521
 522   <section id="s-3.9.6.0">
 523     <title>Version 3.9.6</title>
 524
 525     <para>
 526       Released September, 2014.
 527     </para>
 528
 529     <variablelist>
 530       <varlistentry>
 531         <term>9.1</term>
 532         <listitem>
 533           <para>
 534             The FHS is relaxed to allow a subdirectory of
 535             <filename>/usr/lib</filename> to hold a mixture of
 536             architecture-independent and architecture-dependent files,
 537             though directories entirely composed of
 538             architecture-independent files should be located in
 539             <filename>/usr/share</filename>.
 540           </para>
 541         </listitem>
 542       </varlistentry>
 543       <varlistentry>
 544         <term>9.1</term>
 545         <listitem>
 546           <para>
 547             The FHS requirement for <filename>/usr/local/lib64</filename>
 548             to exist if <filename>/lib64</filename> or
 549             <filename>/usr/lib64</filename> exists is removed.
 550           </para>
 551         </listitem>
 552       </varlistentry>
 553       <varlistentry>
 554         <term>9.1</term>
 555         <listitem>
 556           <para>
 557             An FHS exception has been granted for multiarch include files,
 558             permitting header files to instead be installed to
 559             <filename>/usr/include/triplet</filename>.
 560           </para>
 561         </listitem>
 562       </varlistentry>
 563       <varlistentry>
 564         <term>10.1</term>
 565         <listitem>
 566           <para>
 567             Binaries must not be statically linked with the GNU C library,
 568             see policy for exceptions.
 569           </para>
 570         </listitem>
 571       </varlistentry>
 572       <varlistentry>
 573         <term>4.4</term>
 574         <listitem>
 575           <para>
 576             It is clarified that signature appearing in debian/changelog
 577             should be the details of the person who prepared this release
 578             of the package.
 579           </para>
 580         </listitem>
 581       </varlistentry>
 582       <varlistentry>
 583         <term>11.5</term>
 584         <listitem>
 585           <para>
 586             The default web document root is now
 587             <filename>/var/www/html</filename>
 588           </para>
 589         </listitem>
 590       </varlistentry>
 591       <varlistentry>
 592         <term>virtual</term>
 593         <listitem>
 594           <para>
 595             <literal>java1-runtime</literal> and
 596             <literal>java2-runtime</literal> are removed,
 597             <literal>javaN-runtime</literal> and
 598             <literal>javaN-runtime-headless</literal> are added for all N
 599             between 5 and 9.
 600           </para>
 601         </listitem>
 602       </varlistentry>
 603       <varlistentry>
 604         <term>virtual</term>
 605         <listitem>
 606           <para>
 607             Added <literal>httpd-wsgi</literal> for WSGI capable HTTP
 608             servers.
 609           </para>
 610         </listitem>
 611       </varlistentry>
 612       <varlistentry>
 613         <term>perl</term>
 614         <listitem>
 615           <para>
 616             Perl packages should use the <literal>%Config</literal> hash
 617             to locate module paths instead of hardcoding paths in
 618             <literal>@INC</literal>.
 619           </para>
 620         </listitem>
 621       </varlistentry>
 622       <varlistentry>
 623         <term>perl</term>
 624         <listitem>
 625           <para>
 626             Perl binary modules and any modules installed into
 627             <literal>$Config{vendorarch}</literal> must depend on the
 628             relevant <systemitem role="package">perlapi-*</systemitem>
 629             package.
 630           </para>
 631         </listitem>
 632       </varlistentry>
 633     </variablelist>
 634   </section>
 635
 636   <section id="s-3.9.5.0">
 637     <title>Version 3.9.5</title>
 638
 639     <para>
 640       Released October, 2013.
 641     </para>
 642
 643     <variablelist>
 644       <varlistentry>
 645         <term>5.1</term>
 646         <listitem>
 647           <para>
 648             Control data fields must not start with the hyphen character
 649             (<literal>-</literal>), to avoid potential confusions when
 650             parsing clearsigned control data files that were not properly
 651             unescaped.
 652           </para>
 653         </listitem>
 654       </varlistentry>
 655       <varlistentry>
 656         <term>5.4, 5.6.24</term>
 657         <listitem>
 658           <para>
 659             <literal>Checksums-Sha1</literal> and
 660             <literal>Checksums-Sha256</literal> are now mandatory in
 661             <filename>.dsc</filename> files.
 662           </para>
 663         </listitem>
 664       </varlistentry>
 665       <varlistentry>
 666         <term>5.6.25, 5.8.1</term>
 667         <listitem>
 668           <para>
 669             The <literal>DM-Upload-Allowed</literal> field is obsolete.
 670             Permissions are now granted via
 671             <emphasis>dak-commands</emphasis> files.
 672           </para>
 673         </listitem>
 674       </varlistentry>
 675       <varlistentry>
 676         <term>5.6.27</term>
 677         <listitem>
 678           <para>
 679             New section documenting the <literal>Package-List</literal>
 680             field in Debian source control files.
 681           </para>
 682         </listitem>
 683       </varlistentry>
 684       <varlistentry>
 685         <term>5.6.28</term>
 686         <listitem>
 687           <para>
 688             New section documenting the <literal>Package-Type</literal>
 689             field in source package control files.
 690           </para>
 691         </listitem>
 692       </varlistentry>
 693       <varlistentry>
 694         <term>5.6.29</term>
 695         <listitem>
 696           <para>
 697             New section documenting the <literal>Dgit</literal> field in
 698             Debian source control files.
 699           </para>
 700         </listitem>
 701       </varlistentry>
 702       <varlistentry>
 703         <term>9.1.1.8</term>
 704         <listitem>
 705           <para>
 706             The exception to the FHS for the <filename>/selinux</filename>
 707             was removed.
 708           </para>
 709         </listitem>
 710       </varlistentry>
 711       <varlistentry>
 712         <term>10.7.3</term>
 713         <listitem>
 714           <para>
 715             Packages should remove all obsolete configuration files
 716             without local changes during upgrades.  The
 717             <command>dpkg-maintscript-helper</command> tool, available
 718             from the <systemitem role="package">dpkg</systemitem> package
 719             since <emphasis>Wheezy</emphasis>, can help with this.
 720           </para>
 721         </listitem>
 722       </varlistentry>
 723       <varlistentry>
 724         <term>10.10</term>
 725         <listitem>
 726           <para>
 727             The name of the files and directories installed by binary
 728             packages must be encoded in UTF-8 and should be restricted to
 729             ASCII when possible.  In the system PATH, they must be
 730             restricted to ASCII.
 731           </para>
 732         </listitem>
 733       </varlistentry>
 734       <varlistentry>
 735         <term>11.5.2</term>
 736         <listitem>
 737           <para>
 738             Stop recommending to serve HTML documents from
 739             <filename>/usr/share/doc/<replaceable>package</replaceable></filename>.
 740           </para>
 741         </listitem>
 742       </varlistentry>
 743       <varlistentry>
 744         <term>12.2</term>
 745         <listitem>
 746           <para>
 747             Packages distributing Info documents should use <systemitem
 748             role="package">install-info</systemitem>'s trigger, and do not
 749             need anymore to depend on <literal>dpkg (>= 1.15.4) |
 750             install-info</literal>.
 751           </para>
 752         </listitem>
 753       </varlistentry>
 754       <varlistentry>
 755         <term>debconf</term>
 756         <listitem>
 757           <para>
 758             The <literal>escape</literal> capability is now documented.
 759           </para>
 760         </listitem>
 761       </varlistentry>
 762       <varlistentry>
 763         <term>virtual</term>
 764         <listitem>
 765           <para>
 766             <literal>mp3-decoder</literal> and
 767             <literal>mp3-encoder</literal> are removed.
 768           </para>
 769         </listitem>
 770       </varlistentry>
 771     </variablelist>
 772   </section>
 773
 774   <section id="s-3.9.4.0">
 775     <title>Version 3.9.4</title>
 776
 777     <para>
 778       Released August, 2012.
 779     </para>
 780
 781     <variablelist>
 782       <varlistentry>
 783         <term>2.4</term>
 784         <listitem>
 785           <para>
 786             New <emphasis>tasks</emphasis> archive section.
 787           </para>
 788         </listitem>
 789       </varlistentry>
 790       <varlistentry>
 791         <term>4.9</term>
 792         <listitem>
 793           <para>
 794             <literal>build-arch</literal> and
 795             <literal>build-indep</literal> are now mandatory targets in
 796             <filename>debian/rules</filename>.
 797           </para>
 798         </listitem>
 799       </varlistentry>
 800       <varlistentry>
 801         <term>5.6.26</term>
 802         <listitem>
 803           <para>
 804             New section documenting the <literal>Vcs-*</literal> fields,
 805             which are already in widespread use.  Note the mechanism for
 806             specifying the Git branch used for packaging in the Vcs-Git
 807             field.
 808           </para>
 809         </listitem>
 810       </varlistentry>
 811       <varlistentry>
 812         <term>7.1</term>
 813         <listitem>
 814           <para>
 815             The deprecated relations &lt; and &gt; now must not be used.
 816           </para>
 817         </listitem>
 818       </varlistentry>
 819       <varlistentry>
 820         <term>7.8</term>
 821         <listitem>
 822           <para>
 823             New <literal>Built-Using</literal> field, which must be used
 824             to document the source packages for any binaries that are
 825             incorporated into this package at build time.  This is used to
 826             ensure that the archive meets license requirements for
 827             providing source for all binaries.
 828           </para>
 829         </listitem>
 830       </varlistentry>
 831       <varlistentry>
 832         <term>8.6</term>
 833         <listitem>
 834           <para>
 835             Policy for dependencies between shared libraries and other
 836             packages has been largely rewritten to document the
 837             <literal>symbols</literal> system and more clearly document
 838             handling of shared library ABI changes.
 839             <filename>symbols</filename> files are now recommended over
 840             <filename>shlibs</filename> files in most situations.  All
 841             maintainers of shared library packages should review the
 842             entirety of this section.
 843           </para>
 844         </listitem>
 845       </varlistentry>
 846       <varlistentry>
 847         <term>9.1.1</term>
 848         <listitem>
 849           <para>
 850             Packages must not assume the <filename>/run</filename>
 851             directory exists or is usable without a dependency on
 852             <literal>initscripts (>= 2.88dsf-13.3)</literal> until the
 853             stable release of Debian supports <filename>/run</filename>.
 854           </para>
 855         </listitem>
 856       </varlistentry>
 857       <varlistentry>
 858         <term>9.7</term>
 859         <listitem>
 860           <para>
 861             Packages including MIME configuration can now rely on triggers
 862             and do not need to call update-mime.
 863           </para>
 864         </listitem>
 865       </varlistentry>
 866       <varlistentry>
 867         <term>9.11</term>
 868         <listitem>
 869           <para>
 870             New section documenting general requirements for alternate
 871             init systems and specific requirements for integrating with
 872             upstart.
 873           </para>
 874         </listitem>
 875       </varlistentry>
 876       <varlistentry>
 877         <term>12.5</term>
 878         <listitem>
 879           <para>
 880             All copyright files must be encoded in UTF-8.
 881           </para>
 882         </listitem>
 883       </varlistentry>
 884     </variablelist>
 885   </section>
 886
 887   <section id="s-3.9.3.0">
 888     <title>Version 3.9.3</title>
 889
 890     <para>
 891       Released February, 2012.
 892     </para>
 893
 894     <variablelist>
 895       <varlistentry>
 896         <term>2.4</term>
 897         <listitem>
 898           <para>
 899             New archive sections <emphasis>education</emphasis>,
 900             <emphasis>introspection</emphasis>, and
 901             <emphasis>metapackages</emphasis> added.
 902           </para>
 903         </listitem>
 904       </varlistentry>
 905       <varlistentry>
 906         <term>5.6.8</term>
 907         <listitem>
 908           <para>
 909             The <literal>Architecture</literal> field in
 910             <filename>*.dsc</filename> files may now contain the value
 911             <literal>any all</literal> for source packages building both
 912             architecture-independent and architecture-dependent packages.
 913           </para>
 914         </listitem>
 915       </varlistentry>
 916       <varlistentry>
 917         <term>7.1</term>
 918         <listitem>
 919           <para>
 920             If a dependency is restricted to particular architectures, the
 921             list of architectures must be non-empty.
 922           </para>
 923         </listitem>
 924       </varlistentry>
 925       <varlistentry>
 926         <term>9.1.1</term>
 927         <listitem>
 928           <para>
 929             <filename>/run</filename> is allowed as an exception to the
 930             FHS and replaces <filename>/var/run</filename>.
 931             <filename>/run/lock</filename> replaces
 932             <filename>/var/lock</filename>.  The FHS requirements for the
 933             older directories apply to these directories as well.
 934             Backward compatibility links will be maintained and packages
 935             need not switch to referencing <filename>/run</filename>
 936             directly yet.  Files in <filename>/run</filename> should be
 937             stored in a temporary file system.
 938           </para>
 939         </listitem>
 940       </varlistentry>
 941       <varlistentry>
 942         <term>9.1.4</term>
 943         <listitem>
 944           <para>
 945             New section spelling out the requirements for packages that
 946             use files in <filename>/run</filename>,
 947             <filename>/var/run</filename>, or
 948             <filename>/var/lock</filename>.  This generalizes information
 949             previously only in 9.3.2.
 950           </para>
 951         </listitem>
 952       </varlistentry>
 953       <varlistentry>
 954         <term>9.5</term>
 955         <listitem>
 956           <para>
 957             Cron job file names must not contain <literal>.</literal> or
 958             <literal>+</literal> or they will be ignored by cron.  They
 959             should replace those characters with <literal>_</literal>.  If
 960             a package provides multiple cron job files in the same
 961             directory, they should each start with the package name
 962             (possibly modified as above), <literal>-</literal>, and then
 963             some suitable suffix.
 964           </para>
 965         </listitem>
 966       </varlistentry>
 967       <varlistentry>
 968         <term>9.10</term>
 969         <listitem>
 970           <para>
 971             Packages using doc-base do not need to call install-docs anymore.
 972           </para>
 973         </listitem>
 974       </varlistentry>
 975       <varlistentry>
 976         <term>10.7.4</term>
 977         <listitem>
 978           <para>
 979             Packages that declare the same <literal>conffile</literal> may
 980             see left-over configuration files from each other even if they
 981             conflict.
 982           </para>
 983         </listitem>
 984       </varlistentry>
 985       <varlistentry>
 986         <term>11.8</term>
 987         <listitem>
 988           <para>
 989             The Policy rules around Motif libraries were just a special
 990             case of normal rules for non-free dependencies and were
 991             largely obsolete, so they have been removed.
 992           </para>
 993         </listitem>
 994       </varlistentry>
 995       <varlistentry>
 996         <term>12.5</term>
 997         <listitem>
 998           <para>
 999             <filename>debian/copyright</filename> is no longer required to
1000             list the Debian maintainers involved in the creation of the
1001             package (although note that the requirement to list copyright
1002             information is unchanged).
1003           </para>
1004         </listitem>
1005       </varlistentry>
1006       <varlistentry>
1007         <term>copyright-format</term>
1008         <listitem>
1009           <para>
1010             Version 1.0 of the "Machine-readable
1011             <filename>debian/copyright</filename> file" specification is
1012             included.
1013           </para>
1014         </listitem>
1015       </varlistentry>
1016       <varlistentry>
1017         <term>mime</term>
1018         <listitem>
1019           <para>
1020             This separate document has been retired and and its (short)
1021             contents merged into Policy section 9.7.  There are no changes
1022             to the requirements.
1023           </para>
1024         </listitem>
1025       </varlistentry>
1026       <varlistentry>
1027         <term>perl</term>
1028         <listitem>
1029           <para>
1030             Packages may declare an interest in the
1031             <replaceable>perl-major-upgrade</replaceable> trigger to be
1032             notified of major upgrades of perl.
1033           </para>
1034         </listitem>
1035       </varlistentry>
1036       <varlistentry>
1037         <term>virtual</term>
1038         <listitem>
1039           <para>
1040             <literal>ttf-japanese-{mincho, gothic}</literal> is renamed to
1041             <literal>fonts-japanese-{mincho, gothic}</literal>.
1042           </para>
1043         </listitem>
1044       </varlistentry>
1045     </variablelist>
1046   </section>
1047
1048   <section id="s-3.9.2.0">
1049     <title>Version 3.9.2</title>
1050
1051     <para>
1052       Released April, 2011.
1053     </para>
1054
1055     <variablelist>
1056       <varlistentry>
1057         <term>*</term>
1058         <listitem>
1059           <para>
1060             Multiple clarifications throughout Policy where "installed"
1061             was used and the more precise terms "unpacked" or "configured"
1062             were intended.
1063           </para>
1064         </listitem>
1065       </varlistentry>
1066       <varlistentry>
1067         <term>3.3</term>
1068         <listitem>
1069           <para>
1070             The maintainer address must accept mail from Debian role
1071             accounts and the BTS.  At least one human must be listed with
1072             their personal email address in <literal>Uploaders</literal>
1073             if the maintainer is a shared email address.  The duties of a
1074             maintainer are also clearer.
1075           </para>
1076         </listitem>
1077       </varlistentry>
1078       <varlistentry>
1079         <term>5</term>
1080         <listitem>
1081           <para>
1082             All control fields are now classified as simple, folded, or
1083             multiline, which governs whether their values must be a single
1084             line or may be continued across multiple lines and whether
1085             line breaks are significant.
1086           </para>
1087         </listitem>
1088       </varlistentry>
1089       <varlistentry>
1090         <term>5.1</term>
1091         <listitem>
1092           <para>
1093             Parsers are allowed to accept paragraph separation lines
1094             containing whitespace, but control files should use completely
1095             empty lines.  Ordering of paragraphs is significant.  Field
1096             names must be composed of printable ASCII characters except
1097             colon and must not begin with #.
1098           </para>
1099         </listitem>
1100       </varlistentry>
1101       <varlistentry>
1102         <term>5.6.25</term>
1103         <listitem>
1104           <para>
1105             The <literal>DM-Upload-Allowed</literal> field is now
1106             documented.
1107           </para>
1108         </listitem>
1109       </varlistentry>
1110       <varlistentry>
1111         <term>6.5</term>
1112         <listitem>
1113           <para>
1114             The system state maintainer scripts can rely upon during each
1115             possible invocation is now documented.  In several less-common
1116             cases, this is stricter than Policy had previously documented.
1117             Packages with complex maintainer scripts should be reviewed in
1118             light of this new documentation.
1119           </para>
1120         </listitem>
1121       </varlistentry>
1122       <varlistentry>
1123         <term>7.2</term>
1124         <listitem>
1125           <para>
1126             The impact on system state when maintainer scripts that are
1127             part of a circular dependency are run is now documented.
1128             Circular dependencies are now a should not.
1129           </para>
1130         </listitem>
1131       </varlistentry>
1132       <varlistentry>
1133         <term>7.2</term>
1134         <listitem>
1135           <para>
1136             The system state when <command>postinst</command> and
1137             <command>prerm</command> scripts are run is now documented,
1138             and the documentation of the special case of dependency state
1139             for <command>postrm</command> scripts has been improved.
1140             <command>postrm</command> scripts are required to gracefully
1141             skip actions if their dependencies are not available.
1142           </para>
1143         </listitem>
1144       </varlistentry>
1145       <varlistentry>
1146         <term>9.1.1</term>
1147         <listitem>
1148           <para>
1149             GNU/Hurd systems are allowed <filename>/hurd</filename> and
1150             <filename>/servers</filename> directories in the root
1151             filesystem.
1152           </para>
1153         </listitem>
1154       </varlistentry>
1155       <varlistentry>
1156         <term>9.1.1</term>
1157         <listitem>
1158           <para>
1159             Packages installing to architecture-specific subdirectories of
1160             <filename>/usr/lib</filename> must use the value returned by
1161             <command>dpkg-architecture -qDEB_HOST_MULTIARCH</command>, not
1162             by <command>dpkg-architecture -qDEB_HOST_GNU_TYPE</command>;
1163             this is a path change on i386 architectures and a no-op for
1164             other architectures.
1165           </para>
1166         </listitem>
1167       </varlistentry>
1168       <varlistentry>
1169         <term>virtual</term>
1170         <listitem>
1171           <para>
1172             <literal>mailx</literal> is now a virtual package provided by
1173             packages that install <command>/usr/bin/mailx</command> and
1174             implement at least the POSIX-required interface.
1175           </para>
1176         </listitem>
1177       </varlistentry>
1178     </variablelist>
1179   </section>
1180
1181   <section id="s-3.9.1.0">
1182     <title>Version 3.9.1</title>
1183
1184     <para>
1185       Released July, 2010.
1186     </para>
1187
1188     <variablelist>
1189       <varlistentry>
1190         <term>3.2.1</term>
1191         <listitem>
1192           <para>
1193             Date-based version components should be given as the
1194             four-digit year, two-digit month, and then two-digit day, but
1195             may have embedded punctuation.
1196           </para>
1197         </listitem>
1198       </varlistentry>
1199       <varlistentry>
1200         <term>3.9</term>
1201         <listitem>
1202           <para>
1203             Maintainer scripts must pass <literal>--package</literal> to
1204             <command>dpkg-divert</command> when creating or removing
1205             diversions and must not use <literal>--local</literal>.
1206           </para>
1207         </listitem>
1208       </varlistentry>
1209       <varlistentry>
1210         <term>4.10</term>
1211         <listitem>
1212           <para>
1213             Only <command>dpkg-gencontrol</command> supports variable
1214             substitution.  <command>dpkg-genchanges</command> (for
1215             <filename>*.changes</filename>) and
1216             <command>dpkg-source</command> (for
1217             <filename>*.dsc</filename>) do not.
1218           </para>
1219         </listitem>
1220       </varlistentry>
1221       <varlistentry>
1222         <term>7.1</term>
1223         <listitem>
1224           <para>
1225             Architecture restrictions and wildcards are also allowed in
1226             binary package relationships provided that the binary package
1227             is not architecture-independent.
1228           </para>
1229         </listitem>
1230       </varlistentry>
1231       <varlistentry>
1232         <term>7.4</term>
1233         <listitem>
1234           <para>
1235             <literal>Conflicts</literal> and <literal>Breaks</literal>
1236             should only be used when there are file conflicts or one
1237             package breaks the other, not just because two packages
1238             provide similar functionality but don't interfere.
1239           </para>
1240         </listitem>
1241       </varlistentry>
1242       <varlistentry>
1243         <term>8.1</term>
1244         <listitem>
1245           <para>
1246             The SONAME of a library should change whenever the ABI of the
1247             library changes in a way that isn't backward-compatible.  It
1248             should not change if the library ABI changes are
1249             backward-compatible.  Discourage bundling shared libraries
1250             together in one package.
1251           </para>
1252         </listitem>
1253       </varlistentry>
1254       <varlistentry>
1255         <term>8.4</term>
1256         <listitem>
1257           <para>
1258             Ada Library Information (<filename>*.ali</filename>) files
1259             must be installed read-only.
1260           </para>
1261         </listitem>
1262       </varlistentry>
1263       <varlistentry>
1264         <term>8.6.1, 8.6.2, 8.6.5</term>
1265         <listitem>
1266           <para>
1267             Packages should normally not include a
1268             <filename>shlibs.local</filename> file since we now have
1269             complete <filename>shlibs</filename> coverage.
1270           </para>
1271         </listitem>
1272       </varlistentry>
1273       <varlistentry>
1274         <term>8.6.3</term>
1275         <listitem>
1276           <para>
1277             The SONAME of a library may instead be of the form
1278             <literal><replaceable>name</replaceable>-<replaceable>major-version</replaceable>.so</literal>.
1279           </para>
1280         </listitem>
1281       </varlistentry>
1282       <varlistentry>
1283         <term>10.2</term>
1284         <listitem>
1285           <para>
1286             Libtool <filename>.la</filename> files should not be installed
1287             for public libraries.  If they're required (for
1288             <literal>libltdl</literal>, for instance), the
1289             <literal>dependency_libs</literal> setting should be emptied.
1290             Library packages historically including
1291             <filename>.la</filename> files must continue to include them
1292             (with <literal>dependency_libs</literal> emptied) until all
1293             libraries that depend on that library have removed or emptied
1294             their <filename>.la</filename> files.
1295           </para>
1296         </listitem>
1297       </varlistentry>
1298       <varlistentry>
1299         <term>10.2</term>
1300         <listitem>
1301           <para>
1302             Libraries no longer need to be built with
1303             <literal>-D_REENTRANT</literal>, which was an obsolete
1304             LinuxThreads requirement.  Instead, say explicitly that
1305             libraries should be built with threading support and to be
1306             thread-safe if the library supports this.
1307           </para>
1308         </listitem>
1309       </varlistentry>
1310       <varlistentry>
1311         <term>10.4</term>
1312         <listitem>
1313           <para>
1314             <filename>/bin/sh</filename> scripts may assume that
1315             <command>kill</command> supports an argument of
1316             <literal>-<replaceable>signal</replaceable></literal>, that
1317             <command>kill</command> and <command>trap</command> support
1318             the numeric signals listed in the XSI extension, and that
1319             signal 13 (SIGPIPE) can be trapped with
1320             <command>trap</command>.
1321           </para>
1322         </listitem>
1323       </varlistentry>
1324       <varlistentry>
1325         <term>10.8</term>
1326         <listitem>
1327           <para>
1328             Use of
1329             <filename>/etc/logrotate.d/<replaceable>package</replaceable></filename>
1330             for logrotate rules is now recommended.
1331           </para>
1332         </listitem>
1333       </varlistentry>
1334       <varlistentry>
1335         <term>10.9</term>
1336         <listitem>
1337           <para>
1338             Control information files should be owned by
1339             <literal>root:root</literal> and either mode 644 or mode 755.
1340           </para>
1341         </listitem>
1342       </varlistentry>
1343       <varlistentry>
1344         <term>11.4, 11.8.3, 11.8.4</term>
1345         <listitem>
1346           <para>
1347             Packages providing alternatives for <command>editor</command>,
1348             <command>pager</command>,
1349             <command>x-terminal-emulator</command>, or
1350             <command>x-window-manager</command> should also provide a
1351             slave alternative for the corresponding manual page.
1352           </para>
1353         </listitem>
1354       </varlistentry>
1355       <varlistentry>
1356         <term>11.5</term>
1357         <listitem>
1358           <para>
1359             Cgi-bin executable files may be installed in subdirectories of
1360             <filename>/usr/lib/cgi-bin</filename> and web servers should
1361             serve out executables in those subdirectories.
1362           </para>
1363         </listitem>
1364       </varlistentry>
1365       <varlistentry>
1366         <term>12.5</term>
1367         <listitem>
1368           <para>
1369             The GPL version 1 is now included in common-licenses and
1370             should be referenced from there instead of included in the
1371             <filename>copyright</filename> file.
1372           </para>
1373         </listitem>
1374       </varlistentry>
1375     </variablelist>
1376   </section>
1377
1378   <section id="s-3.9.0.0">
1379     <title>Version 3.9.0</title>
1380
1381     <para>
1382       Released June, 2010.
1383     </para>
1384
1385     <variablelist>
1386       <varlistentry>
1387         <term>4.4, 5.6.15</term>
1388         <listitem>
1389           <para>
1390             The required format for the date in a changelog entry and in
1391             the Date control field is now precisely specified.
1392           </para>
1393         </listitem>
1394       </varlistentry>
1395       <varlistentry>
1396         <term>5.1</term>
1397         <listitem>
1398           <para>
1399             A control paragraph must not contain more than one instance of
1400             a particular field name.
1401           </para>
1402         </listitem>
1403       </varlistentry>
1404       <varlistentry>
1405         <term>5.4, 5.5, 5.6.24</term>
1406         <listitem>
1407           <para>
1408             The <literal>Checksums-Sha1</literal> and
1409             <literal>Checksums-Sha256</literal> fields in
1410             <filename>*.dsc</filename> and <filename>*.changes</filename>
1411             files are now documented and recommended.
1412           </para>
1413         </listitem>
1414       </varlistentry>
1415       <varlistentry>
1416         <term>5.5, 5.6.16</term>
1417         <listitem>
1418           <para>
1419             The <literal>Format</literal> field of
1420             <filename>.changes</filename> files is now 1.8.  The
1421             <literal>Format</literal> field syntax for source package
1422             <filename>.dsc</filename> files allows a subtype in
1423             parentheses, and it is used for a different purpose than the
1424             <literal>Format</literal> field for
1425             <filename>.changes</filename> files.
1426           </para>
1427         </listitem>
1428       </varlistentry>
1429       <varlistentry>
1430         <term>5.6.2</term>
1431         <listitem>
1432           <para>
1433             The syntax of the <literal>Maintainer</literal> field is now
1434             must rather than should.
1435           </para>
1436         </listitem>
1437       </varlistentry>
1438       <varlistentry>
1439         <term>5.6.3</term>
1440         <listitem>
1441           <para>
1442             The comma separating entries in <literal>Uploaders</literal>
1443             is now must rather than should.
1444           </para>
1445         </listitem>
1446       </varlistentry>
1447       <varlistentry>
1448         <term>5.6.8, 7.1, 11.1.1</term>
1449         <listitem>
1450           <para>
1451             Architecture wildcards may be used in addition to specific
1452             architectures in <filename>debian/control</filename> and
1453             <filename>*.dsc</filename> Architecture fields, and in
1454             architecture restrictions in build relationships.
1455           </para>
1456         </listitem>
1457       </varlistentry>
1458       <varlistentry>
1459         <term>6.3</term>
1460         <listitem>
1461           <para>
1462             Maintainer scripts are no longer guaranteed to run with a
1463             controlling terminal and must be able to fall back to
1464             noninteractive behavior (debconf handles this).  Maintainer
1465             scripts may abort if there is no controlling terminal and no
1466             reasonable default for a high-priority question, but should
1467             avoid this if possible.
1468           </para>
1469         </listitem>
1470       </varlistentry>
1471       <varlistentry>
1472         <term>7.3, 7.6.1</term>
1473         <listitem>
1474           <para>
1475             <literal>Breaks</literal> should be used with
1476             <literal>Replaces</literal> for moving files between packages.
1477           </para>
1478         </listitem>
1479       </varlistentry>
1480       <varlistentry>
1481         <term>7.4</term>
1482         <listitem>
1483           <para>
1484             <literal>Breaks</literal> should normally be used instead of
1485             <literal>Conflicts</literal> for transient issues and moving
1486             files between packages.  New documentation of when each should
1487             be used.
1488           </para>
1489         </listitem>
1490       </varlistentry>
1491       <varlistentry>
1492         <term>7.5</term>
1493         <listitem>
1494           <para>
1495             Use <literal>Conflicts</literal> with
1496             <literal>Provides</literal> if only one provider of a virtual
1497             facility can be installed at a time.
1498           </para>
1499         </listitem>
1500       </varlistentry>
1501       <varlistentry>
1502         <term>8.4</term>
1503         <listitem>
1504           <para>
1505             All shared library development files are no longer required to
1506             be in the <literal>-dev</literal> package, only be available
1507             when the <literal>-dev</literal> package is installed.  This
1508             allows the <literal>-dev</literal> package to be split as long
1509             as it depends on the additional packages.
1510           </para>
1511         </listitem>
1512       </varlistentry>
1513       <varlistentry>
1514         <term>9.2.2</term>
1515         <listitem>
1516           <para>
1517             The UID range of user accounts is extended to 1000-59999.
1518           </para>
1519         </listitem>
1520       </varlistentry>
1521       <varlistentry>
1522         <term>9.3.2, 10.4</term>
1523         <listitem>
1524           <para>
1525             <filename>init.d</filename> scripts are a possible exception
1526             from the normal requirement to use <literal>set -e</literal>
1527             in each shell script.
1528           </para>
1529         </listitem>
1530       </varlistentry>
1531       <varlistentry>
1532         <term>12.5</term>
1533         <listitem>
1534           <para>
1535             The UCB BSD license was removed from the list of licenses that
1536             should be referenced from
1537             <filename>/usr/share/common-licenses/BSD</filename>.  It
1538             should instead be included directly in
1539             <filename>debian/copyright</filename>, although it will still
1540             be in common-licenses for the time being.
1541           </para>
1542         </listitem>
1543       </varlistentry>
1544       <varlistentry>
1545         <term>debconf</term>
1546         <listitem>
1547           <para>
1548             <literal>SETTITLE</literal> is now documented (it has been
1549             supported for some time).  <literal>SETTITLE</literal> is like
1550             <literal>TITLE</literal> but takes a template instead of a
1551             string to allow translation.
1552           </para>
1553         </listitem>
1554       </varlistentry>
1555       <varlistentry>
1556         <term>perl</term>
1557         <listitem>
1558           <para>
1559             <systemitem role="package">perl-base</systemitem> now provides
1560             <systemitem
1561             role="package">perlapi-<replaceable>abiname</replaceable></systemitem>
1562             instead of a package based solely on the Perl version.  Perl
1563             packages must now depend on <systemitem
1564             role="package">perlapi-$Config{debian_abi}</systemitem>,
1565             falling back on <literal>$Config{version}</literal> if
1566             <literal>$Config{debian_abi}</literal> is not set.
1567           </para>
1568         </listitem>
1569       </varlistentry>
1570       <varlistentry>
1571         <term>perl</term>
1572         <listitem>
1573           <para>
1574             Packages using <filename>Makefile.PL</filename> should use
1575             <literal>DESTDIR</literal> rather than
1576             <literal>PREFIX</literal> to install into the package staging
1577             area.  <literal>PREFIX</literal> only worked due to a
1578             Debian-local patch.
1579           </para>
1580         </listitem>
1581       </varlistentry>
1582     </variablelist>
1583   </section>
1584
1585   <section id="s-3.8.4.0">
1586     <title>Version 3.8.4</title>
1587
1588     <para>
1589       Released January, 2010.
1590     </para>
1591
1592     <variablelist>
1593       <varlistentry>
1594         <term>9.1.1</term>
1595         <listitem>
1596           <para>
1597             An FHS exception has been granted for multiarch libraries.
1598             Permitting files to instead be installed to
1599             <filename>/lib/triplet</filename> and
1600             <filename>/usr/lib/triplet</filename> directories.
1601           </para>
1602         </listitem>
1603       </varlistentry>
1604       <varlistentry>
1605         <term>10.6</term>
1606         <listitem>
1607           <para>
1608             Packages may not contain named pipes and should instead create
1609             them in postinst and remove them in prerm or postrm.
1610           </para>
1611         </listitem>
1612       </varlistentry>
1613       <varlistentry>
1614         <term>9.1.1</term>
1615         <listitem>
1616           <para>
1617             <filename>/sys</filename> and <filename>/selinux</filename>
1618             directories are explicitly allowed as an exception to the FHS.
1619           </para>
1620         </listitem>
1621       </varlistentry>
1622     </variablelist>
1623   </section>
1624
1625   <section id="s-3.8.3.0">
1626     <title>Version 3.8.3</title>
1627
1628     <para>
1629       Released August, 2009.
1630     </para>
1631
1632     <variablelist>
1633       <varlistentry>
1634         <term>4.9</term>
1635         <listitem>
1636           <para>
1637             DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables are now documented
1638             and recommended over GNU-style variables for that information.
1639           </para>
1640         </listitem>
1641       </varlistentry>
1642       <varlistentry>
1643         <term>5.6.8</term>
1644         <listitem>
1645           <para>
1646             Source package Architecture fields may contain
1647             <emphasis>all</emphasis> in combination with other
1648             architectures.  Clarify when <emphasis>all</emphasis> and
1649             <emphasis>any</emphasis> may be used in different versions of
1650             the field.
1651           </para>
1652         </listitem>
1653       </varlistentry>
1654       <varlistentry>
1655         <term>5.6.14</term>
1656         <listitem>
1657           <para>
1658             The Debian archive software does not support uploading to
1659             multiple distributions with one <filename>*.changes</filename>
1660             file.
1661           </para>
1662         </listitem>
1663       </varlistentry>
1664       <varlistentry>
1665         <term>5.6.19</term>
1666         <listitem>
1667           <para>
1668             The Binary field may span multiple lines.
1669           </para>
1670         </listitem>
1671       </varlistentry>
1672       <varlistentry>
1673         <term>10.2</term>
1674         <listitem>
1675           <para>
1676             Shared library packages are no longer allowed to install
1677             libraries in a non-standard location and modify
1678             <filename>ld.so.conf</filename>.  Packages should either be
1679             installed in a standard library directory or packages using
1680             them should be built with RPATH.
1681           </para>
1682         </listitem>
1683       </varlistentry>
1684       <varlistentry>
1685         <term>11.8.7</term>
1686         <listitem>
1687           <para>
1688             Installation directories for X programs have been clarified.
1689             Packages are no longer required to pre-depend on x11-common
1690             before installing into <filename>/usr/include/X11</filename>
1691             and <filename>/usr/lib/X11</filename>.
1692           </para>
1693         </listitem>
1694       </varlistentry>
1695       <varlistentry>
1696         <term>12.1</term>
1697         <listitem>
1698           <para>
1699             Manual pages are no longer required to contain only characters
1700             representable in the legacy encoding for that language.
1701           </para>
1702         </listitem>
1703       </varlistentry>
1704       <varlistentry>
1705         <term>12.1</term>
1706         <listitem>
1707           <para>
1708             Localized man pages should either be kept up-to-date with the
1709             original version or warn that they're not up-to-date, either
1710             with warning text or by showing missing or changed portions in
1711             the original language.
1712           </para>
1713         </listitem>
1714       </varlistentry>
1715       <varlistentry>
1716         <term>12.2</term>
1717         <listitem>
1718           <para>
1719             install-info is now handled via triggers so packages no longer
1720             need to invoke it in maintainer scripts.  Info documents
1721             should now have directory sections and entries in the
1722             document.  Packages containing info documents should add a
1723             dependency to support partial upgrades.
1724           </para>
1725         </listitem>
1726       </varlistentry>
1727       <varlistentry>
1728         <term>perl</term>
1729         <listitem>
1730           <para>
1731             The requirement for Perl modules to have a versioned Depend
1732             and Build-Depend on <literal>perl &gt;= 5.6.0-16</literal> has
1733             been removed.
1734           </para>
1735         </listitem>
1736       </varlistentry>
1737     </variablelist>
1738   </section>
1739
1740   <section id="s-3.8.2.0">
1741     <title>Version 3.8.2</title>
1742
1743     <para>
1744       Released June, 2009.
1745     </para>
1746
1747     <variablelist>
1748       <varlistentry>
1749         <term>2.4</term>
1750         <listitem>
1751           <para>
1752             The list of archive sections has been significantly expanded.
1753             See <ulink
1754             url="http://lists.debian.org/debian-devel-announce/2009/03/msg00010.html">this
1755             debian-devel-announce message</ulink> for the list of new
1756             sections and rules for how to categorize packages.
1757           </para>
1758         </listitem>
1759       </varlistentry>
1760       <varlistentry>
1761         <term>3.9.1</term>
1762         <listitem>
1763           <para>
1764             All packages must use debconf or equivalent for user
1765             prompting, though essential packages or their dependencies may
1766             also fall back on other methods.
1767           </para>
1768         </listitem>
1769       </varlistentry>
1770       <varlistentry>
1771         <term>5.6.1</term>
1772         <listitem>
1773           <para>
1774             The requirements for source package names are now explicitly
1775             spelled out.
1776           </para>
1777         </listitem>
1778       </varlistentry>
1779       <varlistentry>
1780         <term>9.1</term>
1781         <listitem>
1782           <para>
1783             Legacy XFree86 servers no longer get a special exception from
1784             the FHS permitting <filename>/etc/X11/XF86Config-4</filename>.
1785           </para>
1786         </listitem>
1787       </varlistentry>
1788       <varlistentry>
1789         <term>9.1.3</term>
1790         <listitem>
1791           <para>
1792             Removed obsolete dependency requirements for packages that use
1793             <filename>/var/mail</filename>.
1794           </para>
1795         </listitem>
1796       </varlistentry>
1797       <varlistentry>
1798         <term>11.8.5</term>
1799         <listitem>
1800           <para>
1801             Speedo fonts are now deprecated.  The X backend was disabled
1802             starting in lenny.
1803           </para>
1804         </listitem>
1805       </varlistentry>
1806       <varlistentry>
1807         <term>12.5</term>
1808         <listitem>
1809           <para>
1810             The GNU Free Documentation License version 1.3 is included in
1811             common-licenses and should be referenced from there.
1812           </para>
1813         </listitem>
1814       </varlistentry>
1815     </variablelist>
1816   </section>
1817
1818   <section id="s-3.8.1.0">
1819     <title>Version 3.8.1</title>
1820
1821     <para>
1822       Released March, 2009.
1823     </para>
1824
1825     <variablelist>
1826       <varlistentry>
1827         <term>3.8</term>
1828         <listitem>
1829           <para>
1830             Care should be taken when adding functionality to essential
1831             and such additions create an obligation to support that
1832             functionality in essential forever unless significant work is
1833             done.
1834           </para>
1835         </listitem>
1836       </varlistentry>
1837       <varlistentry>
1838         <term>4.4</term>
1839         <listitem>
1840           <para>
1841             Changelog files must be encoded in UTF-8.
1842           </para>
1843         </listitem>
1844       </varlistentry>
1845       <varlistentry>
1846         <term>4.4</term>
1847         <listitem>
1848           <para>
1849             Some format requirements for changelog files are now "must"
1850             instead of "should."
1851           </para>
1852         </listitem>
1853       </varlistentry>
1854       <varlistentry>
1855         <term>4.4.1</term>
1856         <listitem>
1857           <para>
1858             Alternative changelog formats have been removed.  Debian only
1859             supports one changelog format for the Debian Archive.
1860           </para>
1861         </listitem>
1862       </varlistentry>
1863       <varlistentry>
1864         <term>4.9.1</term>
1865         <listitem>
1866           <para>
1867             New nocheck option for DEB_BUILD_OPTIONS indicating any
1868             build-time test suite provided by the package should not be
1869             run.
1870           </para>
1871         </listitem>
1872       </varlistentry>
1873       <varlistentry>
1874         <term>5.1</term>
1875         <listitem>
1876           <para>
1877             All control files must be encoded in UTF-8.
1878           </para>
1879         </listitem>
1880       </varlistentry>
1881       <varlistentry>
1882         <term>5.2</term>
1883         <listitem>
1884           <para>
1885             <filename>debian/control</filename> allows comment lines
1886             starting with # with no preceding whitespace.
1887           </para>
1888         </listitem>
1889       </varlistentry>
1890       <varlistentry>
1891         <term>9.3</term>
1892         <listitem>
1893           <para>
1894             Init scripts ending in .sh are not handled specially.  They
1895             are not sourced and are not guaranteed to be run by
1896             <command>/bin/sh</command> regardless of the #!  line.  This
1897             brings Policy in line with the long-standing behavior of the
1898             init system in Debian.
1899           </para>
1900         </listitem>
1901       </varlistentry>
1902       <varlistentry>
1903         <term>9.3.2</term>
1904         <listitem>
1905           <para>
1906             The start action of an init script must exit successfully and
1907             not start the daemon again if it's already running.
1908           </para>
1909         </listitem>
1910       </varlistentry>
1911       <varlistentry>
1912         <term>9.3.2</term>
1913         <listitem>
1914           <para>
1915             <filename>/var/run</filename> and
1916             <filename>/var/lock</filename> may be mounted as temporary
1917             filesystems, and init scripts must therefore create any
1918             necessary subdirectories dynamically.
1919           </para>
1920         </listitem>
1921       </varlistentry>
1922       <varlistentry>
1923         <term>10.4</term>
1924         <listitem>
1925           <para>
1926             <filename>/bin/sh</filename> scripts may assume that local can
1927             take multiple variable arguments and supports assignment.
1928           </para>
1929         </listitem>
1930       </varlistentry>
1931       <varlistentry>
1932         <term>11.6</term>
1933         <listitem>
1934           <para>
1935             User mailboxes may be mode 600 and owned by the user rather
1936             than mode 660, owned by user, and group mail.
1937           </para>
1938         </listitem>
1939       </varlistentry>
1940     </variablelist>
1941   </section>
1942
1943   <section id="s-3.8.0.0">
1944     <title>Version 3.8.0</title>
1945
1946     <para>
1947       Released June, 2008.
1948     </para>
1949
1950     <variablelist>
1951       <varlistentry>
1952         <term>2.4, 3.7</term>
1953         <listitem>
1954           <para>
1955             The base section has been removed.  contrib and non-free have
1956             been removed from the section list; they are only categories.
1957             The base system is now defined by priority.
1958           </para>
1959         </listitem>
1960       </varlistentry>
1961       <varlistentry>
1962         <term>4.9</term>
1963         <listitem>
1964           <para>
1965             If <command>dpkg-source -x</command> doesn't provide the
1966             source that will be compiled, a debian/rules patch target is
1967             recommended and should do whatever else is necessary.
1968           </para>
1969         </listitem>
1970       </varlistentry>
1971       <varlistentry>
1972         <term>4.9.1, 10.1</term>
1973         <listitem>
1974           <para>
1975             Standardized the format of DEB_BUILD_OPTIONS.  Specified
1976             permitted characters for tags, required that tags be
1977             whitespace-separated, allowed packages to assume
1978             non-conflicting tags, and required unknown flags be ignored.
1979           </para>
1980         </listitem>
1981       </varlistentry>
1982       <varlistentry>
1983         <term>4.9.1</term>
1984         <listitem>
1985           <para>
1986             Added parallel=n to the standardized DEB_BUILD_OPTIONS tags,
1987             indicating that a package should be built using up to n
1988             parallel processes if the package supports it
1989           </para>
1990         </listitem>
1991       </varlistentry>
1992       <varlistentry>
1993         <term>4.13</term>
1994         <listitem>
1995           <para>
1996             Debian packages should not use convenience copies of code from
1997             other packages unless the included package is explicitly
1998             intended to be used that way.
1999           </para>
2000         </listitem>
2001       </varlistentry>
2002       <varlistentry>
2003         <term>4.14</term>
2004         <listitem>
2005           <para>
2006             If dpkg-source -x doesn't produce source ready for editing and
2007             building with dpkg-buildpackage, packages should include a
2008             <filename>debian/README.source</filename> file explaining how
2009             to generate the patched source, add a new modification, and
2010             remove an existing modification.  This file may also be used
2011             to document packaging a new upstream release and any other
2012             complexity of the Debian build process.
2013           </para>
2014         </listitem>
2015       </varlistentry>
2016       <varlistentry>
2017         <term>5.6.3</term>
2018         <listitem>
2019           <para>
2020             The Uploaders field in debian/control may be wrapped.
2021           </para>
2022         </listitem>
2023       </varlistentry>
2024       <varlistentry>
2025         <term>5.6.12</term>
2026         <listitem>
2027           <para>
2028             An empty Debian revision is equivalent to a Debian revision of
2029             0 in a version number.
2030           </para>
2031         </listitem>
2032       </varlistentry>
2033       <varlistentry>
2034         <term>5.6.23</term>
2035         <listitem>
2036           <para>
2037             New Homepage field for upstream web sites.
2038           </para>
2039         </listitem>
2040       </varlistentry>
2041       <varlistentry>
2042         <term>6.5, 6.6, 7</term>
2043         <listitem>
2044           <para>
2045             The Breaks field declares that this package breaks another and
2046             prevents installation of the breaking package unless the
2047             package named in Breaks is deconfigured first.  This field
2048             should not be used until the dpkg in Debian stable supports
2049             it.
2050           </para>
2051         </listitem>
2052       </varlistentry>
2053       <varlistentry>
2054         <term>8.1, 8.2</term>
2055         <listitem>
2056           <para>
2057             Clarify which files should go into a shared library package,
2058             into a separate package, or into the -dev package.  Suggest
2059             -tools instead of -runtime for runtime support programs, since
2060             that naming is more common in Debian.
2061           </para>
2062         </listitem>
2063       </varlistentry>
2064       <varlistentry>
2065         <term>9.5</term>
2066         <listitem>
2067           <para>
2068             Files in
2069             <filename>/etc/cron.{hourly,daily,weekly,monthly}</filename>
2070             must be configuration files (upgraded from should).  Mention
2071             the hourly directory.
2072           </para>
2073         </listitem>
2074       </varlistentry>
2075       <varlistentry>
2076         <term>11.8.6</term>
2077         <listitem>
2078           <para>
2079             Packages providing <filename>/etc/X11/Xresources</filename>
2080             files need not conflict with <literal>xbase (&lt;&lt;
2081             3.3.2.3a-2)</literal>, which is long-obsolete.
2082           </para>
2083         </listitem>
2084       </varlistentry>
2085       <varlistentry>
2086         <term>12.1</term>
2087         <listitem>
2088           <para>
2089             Manual pages in locale-specific directories should use either
2090             the legacy encoding for that directory or UTF-8.  Country
2091             names should not be included in locale-specific manual page
2092             directories unless indicating a significant difference in the
2093             language.  All characters in the manual page source should be
2094             representable in the legacy encoding for a locale even if the
2095             man page is encoded in UTF-8.
2096           </para>
2097         </listitem>
2098       </varlistentry>
2099       <varlistentry>
2100         <term>12.5</term>
2101         <listitem>
2102           <para>
2103             The Apache 2.0 license is now in common-licenses and should be
2104             referenced rather than quoted in
2105             <filename>debian/copyright</filename>.
2106           </para>
2107         </listitem>
2108       </varlistentry>
2109       <varlistentry>
2110         <term>12.5</term>
2111         <listitem>
2112           <para>
2113             Packages in contrib and non-free should state in the copyright
2114             file that the package is not part of Debian GNU/Linux and
2115             briefly explain why.
2116           </para>
2117         </listitem>
2118       </varlistentry>
2119       <varlistentry>
2120         <term>debconf</term>
2121         <listitem>
2122           <para>
2123             Underscore (_) is allowed in debconf template names.
2124           </para>
2125         </listitem>
2126       </varlistentry>
2127     </variablelist>
2128   </section>
2129
2130   <section id="s-3.7.3.0">
2131     <title>Version 3.7.3</title>
2132
2133     <para>
2134       Released December, 2007.
2135     </para>
2136
2137     <variablelist>
2138       <varlistentry>
2139         <term>5.6.12</term>
2140         <listitem>
2141           <para>
2142             Package version numbers may contain tildes, which sort before
2143             anything, even the end of a part.
2144           </para>
2145         </listitem>
2146       </varlistentry>
2147       <varlistentry>
2148         <term>10.4</term>
2149         <listitem>
2150           <para>
2151             Scripts may assume that <filename>/bin/sh</filename> supports
2152             local (at a basic level) and that its test builtin (if any)
2153             supports -a and -o binary logical operators.
2154           </para>
2155         </listitem>
2156       </varlistentry>
2157       <varlistentry>
2158         <term>8.5</term>
2159         <listitem>
2160           <para>
2161             The substitution variable ${binary:Version} should be used in
2162             place of ${Source-Version} for dependencies between packages
2163             of the same library.
2164           </para>
2165         </listitem>
2166       </varlistentry>
2167       <varlistentry>
2168         <term>menu policy</term>
2169         <listitem>
2170           <para>
2171             Substantial reorganization and renaming of sections in the
2172             Debian menu structure.  Packages with menu entries should be
2173             reviewed to see if the menu section has been renamed or if one
2174             of the new sections would be more appropriate.
2175           </para>
2176         </listitem>
2177       </varlistentry>
2178       <varlistentry>
2179         <term>5.6.1</term>
2180         <listitem>
2181           <para>
2182             The Source field in a .changes file may contain a version
2183             number in parentheses.
2184           </para>
2185         </listitem>
2186       </varlistentry>
2187       <varlistentry>
2188         <term>5.6.17</term>
2189         <listitem>
2190           <para>
2191             The acceptable values for the Urgency field are low, medium,
2192             high, critical, or emergency.
2193           </para>
2194         </listitem>
2195       </varlistentry>
2196       <varlistentry>
2197         <term>8.6</term>
2198         <listitem>
2199           <para>
2200             The shlibs file now allows an optional type field, indicating
2201             the type of package for which the line is valid.  The only
2202             currently supported type is udeb, used with packages for the
2203             Debian Installer.
2204           </para>
2205         </listitem>
2206       </varlistentry>
2207       <varlistentry>
2208         <term>3.9.1</term>
2209         <listitem>
2210           <para>
2211             Packages following the Debian Configuration management
2212             specification must allow for translation of their messages by
2213             using a gettext-based system such as po-debconf.
2214           </para>
2215         </listitem>
2216       </varlistentry>
2217       <varlistentry>
2218         <term>12.5</term>
2219         <listitem>
2220           <para>
2221             GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and
2222             should be referenced rather than quoted in debian/copyright.
2223           </para>
2224         </listitem>
2225       </varlistentry>
2226     </variablelist>
2227   </section>
2228
2229   <section id="s-3.7.2.2">
2230     <title>Version 3.7.2.2</title>
2231
2232     <para>
2233       Released October, 2006.
2234     </para>
2235     <para>
2236       This release broke the normal rule against introducing normative
2237       changes without changing the major patch level.
2238     </para>
2239
2240     <variablelist>
2241       <varlistentry>
2242         <term>6.1</term>
2243         <listitem>
2244           <para>
2245             Maintainer scripts must not be world writeable (up from a
2246             should to a must)
2247           </para>
2248         </listitem>
2249       </varlistentry>
2250     </variablelist>
2251   </section>
2252
2253   <section id="s-3.7.2.0">
2254     <title>Version 3.7.2</title>
2255
2256     <para>
2257       Released April, 2006.
2258     </para>
2259
2260     <variablelist>
2261       <varlistentry>
2262         <term>11.5</term>
2263         <listitem>
2264           <para>
2265             Revert the cgi-lib change.
2266           </para>
2267         </listitem>
2268       </varlistentry>
2269     </variablelist>
2270   </section>
2271
2272   <section id="s-3.7.1.0">
2273     <title>Version 3.7.1</title>
2274
2275     <para>
2276       Released April, 2006.
2277     </para>
2278
2279     <variablelist>
2280       <varlistentry>
2281         <term>10.2</term>
2282         <listitem>
2283           <para>
2284             It is now possible to create shared libraries without
2285             relocatable code (using -fPIC) in certain exceptional cases,
2286             provided some procedures are followed, and for creating static
2287             libraries with relocatable code (again, using -fPIC).
2288             Discussion on debian-devel@lists.debian.org, getting a rough
2289             consensus, and documenting it in README.Debian constitute most
2290             of the process.
2291           </para>
2292         </listitem>
2293       </varlistentry>
2294       <varlistentry>
2295         <term>11.8.7</term>
2296         <listitem>
2297           <para>
2298             Packages should install any relevant files into the
2299             directories <filename>/usr/include/X11/</filename> and
2300             <filename>/usr/lib/X11/</filename>, but if they do so, they
2301             must pre-depend on <literal>x11-common (&gt;=
2302             1:7.0.0)</literal>
2303           </para>
2304         </listitem>
2305       </varlistentry>
2306     </variablelist>
2307   </section>
2308
2309   <section id="s-3.7.0.0">
2310     <title>Version 3.7.0</title>
2311
2312     <para>
2313       Released April, 2006.
2314     </para>
2315
2316     <variablelist>
2317       <varlistentry>
2318         <term>11.5</term>
2319         <listitem>
2320           <para>
2321             Packages shipping web server CGI files are expected to install
2322             them in <filename>/usr/lib/cgi-lib/</filename> directories.
2323             This location change perhaps should be documented in NEWS
2324           </para>
2325         </listitem>
2326       </varlistentry>
2327       <varlistentry>
2328         <term>11.5</term>
2329         <listitem>
2330           <para>
2331             Web server packages should include a standard scriptAlias of
2332             cgi-lib to <filename>/usr/lib/cgi-lib</filename>.
2333           </para>
2334         </listitem>
2335       </varlistentry>
2336       <varlistentry>
2337         <term>9.1.1</term>
2338         <listitem>
2339           <para>
2340             The version of FHS mandated by policy has been upped to 2.3.
2341             There should be no changes required for most packages, though
2342             new top level directories <filename>/media</filename>,
2343             <filename>/srv</filename>, etc.  may be of interest.
2344           </para>
2345         </listitem>
2346       </varlistentry>
2347       <varlistentry>
2348         <term>5.1, 5.6.3</term>
2349         <listitem>
2350           <para>
2351             All fields, apart from the Uploaders field, in the control
2352             file are supposed to be a single logical line, which may be
2353             spread over multiple physical lines (newline followed by space
2354             is elided).  However, any parser for the control file must
2355             allow the Uploaders field to be spread over multiple physical
2356             lines as well, to prepare for future changes.
2357           </para>
2358         </listitem>
2359       </varlistentry>
2360       <varlistentry>
2361         <term>10.4</term>
2362         <listitem>
2363           <para>
2364             When scripts are installed into a directory in the system
2365             PATH, the script name should not include an extension that
2366             denotes the scripting language currently used to implement it.
2367           </para>
2368         </listitem>
2369       </varlistentry>
2370       <varlistentry>
2371         <term>9.3.3.2</term>
2372         <listitem>
2373           <para>
2374             packages that invoke initscripts now must use invoke-rc.d to
2375             do so since it also pays attention to run levels and other
2376             local constraints.
2377           </para>
2378         </listitem>
2379       </varlistentry>
2380       <varlistentry>
2381         <term>11.8.5.2, 11.8.7, etc</term>
2382         <listitem>
2383           <para>
2384             We no longer use <filename>/usr/X11R6</filename>, since we
2385             have migrated away to using Xorg paths.  This means, for one
2386             thing, fonts live in
2387             <filename>/usr/share/fonts/X11/</filename> now, and
2388             <filename>/usr/X11R6</filename> is gone.
2389           </para>
2390         </listitem>
2391       </varlistentry>
2392     </variablelist>
2393   </section>
2394
2395   <section id="s-3.6.2.0">
2396     <title>Version 3.6.2</title>
2397
2398     <para>
2399       Released June, 2005.
2400     </para>
2401
2402     <variablelist>
2403       <varlistentry>
2404         <term></term>
2405         <listitem>
2406           <para>
2407             Recommend doc-base, and not menu, for registering package
2408             documentation.
2409           </para>
2410         </listitem>
2411       </varlistentry>
2412       <varlistentry>
2413         <term>8.1</term>
2414         <listitem>
2415           <para>
2416             Run time support programs should live in subdirectories of
2417             <filename>/usr/lib/</filename> or
2418             <filename>/usr/share</filename>, and preferably the shared lib
2419             is named the same as the package name (to avoid name
2420             collisions).
2421           </para>
2422         </listitem>
2423       </varlistentry>
2424       <varlistentry>
2425         <term>11.5</term>
2426         <listitem>
2427           <para>
2428             It is recommended that HTTP servers provide an alias /images
2429             to allow packages to share image files with the web server
2430           </para>
2431         </listitem>
2432       </varlistentry>
2433     </variablelist>
2434   </section>
2435
2436   <section id="s-3.6.1.0">
2437     <title>Version 3.6.1</title>
2438
2439     <para>
2440       Released August, 2003.
2441     </para>
2442
2443     <variablelist>
2444       <varlistentry>
2445         <term>3.10.1</term>
2446         <listitem>
2447           <para>
2448             Prompting the user should be done using debconf.  Non debconf
2449             user prompts are now deprecated.
2450           </para>
2451         </listitem>
2452       </varlistentry>
2453     </variablelist>
2454   </section>
2455
2456   <section id="s-3.6.0.0">
2457     <title>Version 3.6.0</title>
2458
2459     <para>
2460       Released July, 2003.
2461     </para>
2462
2463     <variablelist>
2464       <varlistentry>
2465         <term></term>
2466         <listitem>
2467           <para>
2468             Restructuring causing shifts in section numbers and bumping of
2469             the minor version number:
2470           </para>
2471         </listitem>
2472       </varlistentry>
2473       <varlistentry>
2474         <term></term>
2475         <listitem>
2476           <para>
2477             Many packaging manual appendices that were integrated into
2478             policy sections are now empty, and replaced with links to the
2479             Policy.  In particular, the appendices that included the list
2480             of control fields were updated (new fields like Closes,
2481             Changed-By were added) and the list of fields for each of
2482             control, .changes and .dsc files is now in Policy, and they're
2483             marked mandatory, recommended or optional based on the current
2484             practice and the behavior of the deb-building tool-chain.
2485           </para>
2486         </listitem>
2487       </varlistentry>
2488       <varlistentry>
2489         <term></term>
2490         <listitem>
2491           <para>
2492             Elimination of needlessly deep section levels, primarily in
2493             the chapter Debian Archive, from which two new chapters were
2494             split out, Binary packages and Source packages.  What remained
2495             was reordered properly, that is, some sects became sects etc.
2496           </para>
2497         </listitem>
2498       </varlistentry>
2499       <varlistentry>
2500         <term></term>
2501         <listitem>
2502           <para>
2503             Several sections that were redundant, crufty or simply not
2504             designed with any sort of vision, were rearranged according to
2505             the formula that everything should be either in the same place
2506             or properly interlinked.  Some things remained split up
2507             between different chapters when they talked about different
2508             aspects of files: their content, their syntax, and their
2509             placement in the file system.  In particular, see the new
2510             sections about changelog files.
2511           </para>
2512         </listitem>
2513       </varlistentry>
2514       <varlistentry>
2515         <term>menu policy</term>
2516         <listitem>
2517           <para>
2518             Added Games/Simulation and Apps/Education to menu sub-policy
2519           </para>
2520         </listitem>
2521       </varlistentry>
2522       <varlistentry>
2523         <term>C.2.2</term>
2524         <listitem>
2525           <para>
2526             Debian changelogs should be UTF-8 encoded.
2527           </para>
2528         </listitem>
2529       </varlistentry>
2530       <varlistentry>
2531         <term>10.2</term>
2532         <listitem>
2533           <para>
2534             shared libraries must be linked against all libraries that
2535             they use symbols from in the same way that binaries are.
2536           </para>
2537         </listitem>
2538       </varlistentry>
2539       <varlistentry>
2540         <term>7.6</term>
2541         <listitem>
2542           <para>
2543             build-depends-indep need not be satisfied during clean target.
2544           </para>
2545         </listitem>
2546       </varlistentry>
2547     </variablelist>
2548   </section>
2549
2550   <section id="s-3.5.10.0">
2551     <title>Version 3.5.10</title>
2552
2553     <para>
2554       Released May, 2003.
2555     </para>
2556
2557     <variablelist>
2558       <varlistentry>
2559         <term>11.8.3</term>
2560         <listitem>
2561           <para>
2562             packages providing the x-terminal-emulator virtual package
2563             ought to ensure that they interpret the command line exactly
2564             like xterm does.
2565           </para>
2566         </listitem>
2567       </varlistentry>
2568       <varlistentry>
2569         <term>11.8.4</term>
2570         <listitem>
2571           <para>
2572             Window managers compliant with the Window Manager
2573             Specification Project may add 40 points for ranking in the
2574             alternatives
2575           </para>
2576         </listitem>
2577       </varlistentry>
2578     </variablelist>
2579   </section>
2580
2581   <section id="s-3.5.9.0">
2582     <title>Version 3.5.9</title>
2583
2584     <para>
2585       Released March, 2003.
2586     </para>
2587
2588     <variablelist>
2589       <varlistentry>
2590         <term>3.4.2</term>
2591         <listitem>
2592           <para>
2593             The section describing the Description: package field once
2594             again has full details of the long description format.
2595           </para>
2596         </listitem>
2597       </varlistentry>
2598       <varlistentry>
2599         <term>4.2</term>
2600         <listitem>
2601           <para>
2602             Clarified that if a package has non-build-essential
2603             build-dependencies, it should have them listed in the
2604             Build-Depends and related fields (i.e.  it's not merely
2605             optional).
2606           </para>
2607         </listitem>
2608       </varlistentry>
2609       <varlistentry>
2610         <term>9.3.2</term>
2611         <listitem>
2612           <para>
2613             When asked to restart a service that isn't already running,
2614             the init script should start the service.
2615           </para>
2616         </listitem>
2617       </varlistentry>
2618       <varlistentry>
2619         <term>12.6</term>
2620         <listitem>
2621           <para>
2622             If the purpose of a package is to provide examples, then the
2623             example files can be installed into
2624             <filename>/usr/share/doc/package</filename> (rather than
2625             <filename>/usr/share/doc/package/examples</filename>).
2626           </para>
2627         </listitem>
2628       </varlistentry>
2629     </variablelist>
2630   </section>
2631
2632   <section id="s-3.5.8.0">
2633     <title>Version 3.5.8</title>
2634
2635     <para>
2636       Released November, 2002.
2637     </para>
2638
2639     <variablelist>
2640       <varlistentry>
2641         <term>12.7</term>
2642         <listitem>
2643           <para>
2644             It is no longer necessary to keep a log of changes to the
2645             upstream sources in the copyright file.  Instead, all such
2646             changes should be documented in the changelog file.
2647           </para>
2648         </listitem>
2649       </varlistentry>
2650       <varlistentry>
2651         <term>7.6</term>
2652         <listitem>
2653           <para>
2654             <replaceable>Build-Depends</replaceable>,
2655             <replaceable>Build-Conflicts</replaceable>,
2656             <replaceable>Build-Depends-Indep</replaceable>, and
2657             <replaceable>Build-Conflicts-Indep</replaceable> must also be
2658             satisfied when the clean target is called.
2659           </para>
2660         </listitem>
2661       </varlistentry>
2662       <varlistentry>
2663         <term>menu policy</term>
2664         <listitem>
2665           <para>
2666             A new Apps/Science menu section is available
2667           </para>
2668         </listitem>
2669       </varlistentry>
2670       <varlistentry>
2671         <term>debconf policy</term>
2672         <listitem>
2673           <para>
2674             debconf specification cleared up, various changes.
2675           </para>
2676         </listitem>
2677       </varlistentry>
2678       <varlistentry>
2679         <term>12.1</term>
2680         <listitem>
2681           <para>
2682             It is no longer recommended to create symlinks from
2683             nonexistent manual pages to undocumented(7).  Missing manual
2684             pages for programs are still a bug.
2685           </para>
2686         </listitem>
2687       </varlistentry>
2688     </variablelist>
2689   </section>
2690
2691   <section id="s-3.5.7.0">
2692     <title>Version 3.5.7</title>
2693
2694     <para>
2695       Released August, 2002.
2696     </para>
2697
2698     <variablelist>
2699       <varlistentry>
2700         <term></term>
2701         <listitem>
2702           <para>
2703             Packages no longer have to ask permission to call MAKEDEV in
2704             postinst, merely notifying the user ought to be enough.
2705           </para>
2706         </listitem>
2707       </varlistentry>
2708       <varlistentry>
2709         <term>2.2.4</term>
2710         <listitem>
2711           <para>
2712             cryptographic software may now be included in the main archive.
2713           </para>
2714         </listitem>
2715       </varlistentry>
2716       <varlistentry>
2717         <term>3.9</term>
2718         <listitem>
2719           <para>
2720             task packages are no longer permitted; tasks are now created
2721             by a special Tasks: field in the control file.
2722           </para>
2723         </listitem>
2724       </varlistentry>
2725       <varlistentry>
2726         <term>11.8.4</term>
2727         <listitem>
2728           <para>
2729             window managers that support netwm can now add 20 points when
2730             they add themselves as an alternative for
2731             <filename>/usr/bin/x-window-manager</filename>
2732           </para>
2733         </listitem>
2734       </varlistentry>
2735       <varlistentry>
2736         <term>10.1</term>
2737         <listitem>
2738           <para>
2739             The default compilation options have now changed, one should
2740             provide debugging symbols in all cases, and optionally step
2741             back optimization to -O0, depending on the DEB_BUILD_OPTIONS
2742             environment variable.
2743           </para>
2744         </listitem>
2745       </varlistentry>
2746       <varlistentry>
2747         <term>7.6, 4.8</term>
2748         <listitem>
2749           <para>
2750             Added mention of build-arch, build-indep, etc, in describing
2751             the relationships with `Build-Depends', `Build-Conflicts',
2752             `Build-Depends-Indep', and `Build-Conflicts-Indep'.  May need
2753             to review the new rules.
2754           </para>
2755         </listitem>
2756       </varlistentry>
2757       <varlistentry>
2758         <term>8</term>
2759         <listitem>
2760           <para>
2761             Changed rules on how, and when, to invoke ldconfig in
2762             maintainer scripts.  Long rationale.
2763           </para>
2764         </listitem>
2765       </varlistentry>
2766     </variablelist>
2767
2768     <para>
2769       <emphasis>Added the last note in 3.5.6 upgrading checklist item
2770       regarding build rules, please see below</emphasis>
2771     </para>
2772   </section>
2773
2774   <section id="s-3.5.6.0">
2775     <title>Version 3.5.6</title>
2776
2777     <para>
2778       Released July, 2001.
2779     </para>
2780
2781     <variablelist>
2782       <varlistentry>
2783         <term>2.5</term>
2784         <listitem>
2785           <para>
2786             Emacs and TeX are no longer mandated by policy to be priority
2787             standard packages
2788           </para>
2789         </listitem>
2790       </varlistentry>
2791       <varlistentry>
2792         <term>11.5</term>
2793         <listitem>
2794           <para>
2795             Programs that access docs need to do so via
2796             <filename>/usr/share/doc</filename>, and not via
2797             <filename>/usr/doc/</filename> as was the policy previously
2798           </para>
2799         </listitem>
2800       </varlistentry>
2801       <varlistentry>
2802         <term>12.3</term>
2803         <listitem>
2804           <para>
2805             Putting documentation in <filename>/usr/doc</filename> versus
2806             <filename>/usr/share/doc</filename> is now a ``serious''
2807             policy violation.
2808           </para>
2809         </listitem>
2810       </varlistentry>
2811       <varlistentry>
2812         <term>11.5</term>
2813         <listitem>
2814           <para>
2815             For web servers, one should not provide non-local access to
2816             the <filename>/usr/share/doc</filename> hierarchy.  If one
2817             can't provide access controls for the http://localhost/doc/
2818             directory, then it is preferred that one ask permission to
2819             expose that information during the install.
2820           </para>
2821         </listitem>
2822       </varlistentry>
2823       <varlistentry>
2824         <term>7</term>
2825         <listitem>
2826           <para>
2827             There are new rules for build-indep/build-arch targets and
2828             there is a new Build-Depend-Indep semantic.
2829           </para>
2830         </listitem>
2831       </varlistentry>
2832     </variablelist>
2833   </section>
2834
2835   <section id="s-3.5.5.0">
2836     <title>Version 3.5.5</title>
2837
2838     <para>
2839       Released May, 2001.
2840     </para>
2841
2842     <variablelist>
2843       <varlistentry>
2844         <term>12.1</term>
2845         <listitem>
2846           <para>
2847             Manpages should not rely on header information to have
2848             alternative manpage names available; it should only use
2849             symlinks or .so pages to do this
2850           </para>
2851         </listitem>
2852       </varlistentry>
2853       <varlistentry>
2854         <term></term>
2855         <listitem>
2856           <para>
2857             <emphasis>Clarified note in 3.5.3.0 upgrading checklist
2858             regarding examples and templates: this refers only to those
2859             examples used by scripts; see section 10.7.3 for the whole
2860             story</emphasis>
2861           </para>
2862         </listitem>
2863       </varlistentry>
2864       <varlistentry>
2865         <term></term>
2866         <listitem>
2867           <para>
2868             Included a new section 10.9.1 describing the use of
2869             dpkg-statoverride; this does not have the weight of policy
2870           </para>
2871         </listitem>
2872       </varlistentry>
2873       <varlistentry>
2874         <term></term>
2875         <listitem>
2876           <para>
2877             Clarify Standards-Version: you don't need to rebuild your
2878             packages just to change the Standards-Version!
2879           </para>
2880         </listitem>
2881       </varlistentry>
2882       <varlistentry>
2883         <term>10.2</term>
2884         <listitem>
2885           <para>
2886             Plugins are no longer bound by all the rules of shared
2887             libraries
2888           </para>
2889         </listitem>
2890       </varlistentry>
2891       <varlistentry>
2892         <term>X Windows related things:</term>
2893         <listitem>
2894           <variablelist>
2895             <varlistentry>
2896               <term>11.8.1</term>
2897               <listitem>
2898                 <para>
2899                   Clarification of priority levels of X Window System
2900                   related packages
2901                 </para>
2902               </listitem>
2903             </varlistentry>
2904             <varlistentry>
2905               <term>11.8.3</term>
2906               <listitem>
2907                 <para>
2908                   Rules for defining x-terminal-emulator improved
2909                 </para>
2910               </listitem>
2911             </varlistentry>
2912             <varlistentry>
2913               <term>11.8.5</term>
2914               <listitem>
2915                 <para>
2916                   X Font policy rewritten: you must read this if you
2917                   provide fonts for the X Window System
2918                 </para>
2919               </listitem>
2920             </varlistentry>
2921             <varlistentry>
2922               <term>11.8.6</term>
2923               <listitem>
2924                 <para>
2925                   Packages must not ship
2926                   <filename>/usr/X11R6/lib/X11/app-defaults/</filename>
2927                 </para>
2928               </listitem>
2929             </varlistentry>
2930             <varlistentry>
2931               <term>11.8.7</term>
2932               <listitem>
2933                 <para>
2934                   X-related packages should usually use the regular FHS
2935                   locations; imake-using packages are exempted from this
2936                 </para>
2937               </listitem>
2938             </varlistentry>
2939             <varlistentry>
2940               <term>11.8.8</term>
2941               <listitem>
2942                 <para>
2943                   OpenMotif linked binaries have the same rules as
2944                   OSF/Motif-linked ones
2945                 </para>
2946               </listitem>
2947             </varlistentry>
2948           </variablelist>
2949         </listitem>
2950       </varlistentry>
2951     </variablelist>
2952   </section>
2953
2954   <section id="s-3.5.4.0">
2955     <title>Version 3.5.4</title>
2956
2957     <para>
2958       Released April, 2001.
2959     </para>
2960
2961     <variablelist>
2962       <varlistentry>
2963         <term>11.6</term>
2964         <listitem>
2965           <para>
2966             The system-wide mail directory is now /var/mail, no longer
2967             /var/spool/mail.  Any packages accessing the mail spool should
2968             access it via /var/mail and include a suitable Depends field;
2969           </para>
2970         </listitem>
2971       </varlistentry>
2972       <varlistentry>
2973         <term>11.9; perl-policy</term>
2974         <listitem>
2975           <para>
2976             The perl policy is now part of Debian policy proper.  Perl
2977             programs and modules should follow the current Perl policy
2978           </para>
2979         </listitem>
2980       </varlistentry>
2981     </variablelist>
2982   </section>
2983
2984   <section id="s-3.5.3.0">
2985     <title>Version 3.5.3</title>
2986
2987     <para>
2988       Released April, 2001.
2989     </para>
2990
2991     <variablelist>
2992       <varlistentry>
2993         <term>7.1</term>
2994         <listitem>
2995           <para>
2996             Build-Depends arch syntax has been changed to be less
2997             ambiguous.  This should not affect any current packages
2998           </para>
2999         </listitem>
3000       </varlistentry>
3001       <varlistentry>
3002         <term>10.7.3</term>
3003         <listitem>
3004           <para>
3005             Examples and templates files for use by scripts should now
3006             live in <filename>/usr/share/&lt;package&gt;</filename> or
3007             <filename>/usr/lib/&lt;package&gt;</filename>, with symbolic
3008             links from
3009             <filename>/usr/share/doc/&lt;package&gt;/examples</filename>
3010             as needed
3011           </para>
3012         </listitem>
3013       </varlistentry>
3014     </variablelist>
3015   </section>
3016
3017   <section id="s-3.5.2.0">
3018     <title>Version 3.5.2</title>
3019
3020     <para>
3021       Released February, 2001.
3022     </para>
3023
3024     <variablelist>
3025       <varlistentry>
3026         <term>11.8.6</term>
3027         <listitem>
3028           <para>
3029             X app-defaults directory has moved from
3030             <filename>/usr/X11R6/lib/X11/app-defaults</filename> to
3031             <filename>/etc/X11/app-defaults</filename>
3032           </para>
3033         </listitem>
3034       </varlistentry>
3035     </variablelist>
3036   </section>
3037
3038   <section id="s-3.5.1.0">
3039     <title>Version 3.5.1</title>
3040
3041     <para>
3042       Released February, 2001.
3043     </para>
3044
3045     <variablelist>
3046       <varlistentry>
3047         <term>8.1</term>
3048         <listitem>
3049           <para>
3050             dpkg-shlibdeps now uses objdump, so shared libraries have to
3051             be run through dpkg-shlibdeps as well as executables
3052           </para>
3053         </listitem>
3054       </varlistentry>
3055     </variablelist>
3056   </section>
3057
3058   <section id="s-3.5.0.0">
3059     <title>Version 3.5.0</title>
3060
3061     <para>
3062       Released January, 2001.
3063     </para>
3064
3065     <variablelist>
3066       <varlistentry>
3067         <term>11.8.5</term>
3068         <listitem>
3069           <para>
3070             Font packages for the X Window System must now declare a
3071             dependency on xutils (>= 4.0.2)
3072           </para>
3073         </listitem>
3074       </varlistentry>
3075     </variablelist>
3076   </section>
3077
3078   <section id="s-3.2.1.1">
3079     <title>Version 3.2.1.1</title>
3080
3081     <para>
3082       Released January, 2001.
3083     </para>
3084     <para>
3085       This release broke the normal rule against introducing normative
3086       changes without changing the major patch level.
3087     </para>
3088
3089     <variablelist>
3090       <varlistentry>
3091         <term>9.3.2</term>
3092         <listitem>
3093           <para>
3094             Daemon startup scripts in <filename>/etc/init.d/</filename>
3095             should not contain modifiable parameters; these should be
3096             moved to a file in <filename>/etc/default/</filename>
3097           </para>
3098         </listitem>
3099       </varlistentry>
3100       <varlistentry>
3101         <term>12.3</term>
3102         <listitem>
3103           <para>
3104             Files in <filename>/usr/share/doc</filename> must not be
3105             referenced by any program.  If such files are needed, they
3106             must be placed in
3107             <filename>/usr/share/&lt;package&gt;/</filename>, and symbolic
3108             links created as required in
3109             <filename>/usr/share/doc/&lt;package&gt;/</filename>
3110           </para>
3111         </listitem>
3112       </varlistentry>
3113       <varlistentry>
3114         <term></term>
3115         <listitem>
3116           <para>
3117             Much of the packaging manual has now been imported into the
3118             policy document
3119           </para>
3120         </listitem>
3121       </varlistentry>
3122     </variablelist>
3123   </section>
3124
3125   <section id="s-3.2.1.0">
3126     <title>Version 3.2.1</title>
3127
3128     <para>
3129       Released August, 2000.
3130     </para>
3131
3132     <variablelist>
3133       <varlistentry>
3134         <term>11.8.1</term>
3135         <listitem>
3136           <para>
3137             A package of priority standard or higher may provide two
3138             binaries, one compiled with support for the X Window System,
3139             and the other without
3140           </para>
3141         </listitem>
3142       </varlistentry>
3143     </variablelist>
3144   </section>
3145
3146   <section id="s-3.2.0.0">
3147     <title>Version 3.2.0</title>
3148
3149     <para>
3150       Released August, 2000.
3151     </para>
3152
3153     <variablelist>
3154       <varlistentry>
3155         <term>10.1</term>
3156         <listitem>
3157           <para>
3158             By default executables should not be built with the debugging
3159             option -g.  Instead, it is recommended to support building the
3160             package with debugging information optionally.
3161           </para>
3162         </listitem>
3163       </varlistentry>
3164       <varlistentry>
3165         <term>12.8</term>
3166         <listitem>
3167           <para>
3168             Policy for packages where the upstream uses HTML changelog
3169             files has been expanded.  In short, a plain text changelog
3170             file should always be generated for the upstream changes
3171           </para>
3172         </listitem>
3173       </varlistentry>
3174       <varlistentry>
3175         <term></term>
3176         <listitem>
3177           <para>
3178             Please note that the new release of the X window system (3.2)
3179             shall probably need sweeping changes in policy
3180           </para>
3181         </listitem>
3182       </varlistentry>
3183       <varlistentry>
3184         <term></term>
3185         <listitem>
3186           <para>
3187             Policy for packages providing the following X-based features
3188             has been codified:
3189           </para>
3190           <variablelist>
3191             <varlistentry>
3192               <term>11.8.2</term>
3193               <listitem>
3194                 <para>
3195                   X server (virtual package xserver)
3196                 </para>
3197               </listitem>
3198             </varlistentry>
3199             <varlistentry>
3200               <term>11.8.3</term>
3201               <listitem>
3202                 <para>
3203                   X terminal emulator (virtual package x-terminal-emulator)
3204                 </para>
3205               </listitem>
3206             </varlistentry>
3207             <varlistentry>
3208               <term>11.8.4</term>
3209               <listitem>
3210                 <para>
3211                   X window manager (virtual package x-window-manager, and
3212                   <filename>/usr/bin/x-window-manager</filename>
3213                   alternative, with priority calculation guidelines)
3214                 </para>
3215               </listitem>
3216             </varlistentry>
3217             <varlistentry>
3218               <term>12.8.5</term>
3219               <listitem>
3220                 <para>
3221                   X fonts (this section has been written from scratch)
3222                 </para>
3223               </listitem>
3224             </varlistentry>
3225             <varlistentry>
3226               <term>11.8.6</term>
3227               <listitem>
3228                 <para>
3229                   X application defaults
3230                 </para>
3231               </listitem>
3232             </varlistentry>
3233           </variablelist>
3234         </listitem>
3235       </varlistentry>
3236       <varlistentry>
3237         <term>11.8.7</term>
3238         <listitem>
3239           <para>
3240             Policy for packages using the X Window System and FHS issues
3241             has been clarified;
3242           </para>
3243         </listitem>
3244       </varlistentry>
3245       <varlistentry>
3246         <term>11.7.3</term>
3247         <listitem>
3248           <para>
3249             No package may contain or make hard links to conffiles
3250           </para>
3251         </listitem>
3252       </varlistentry>
3253       <varlistentry>
3254         <term>8</term>
3255         <listitem>
3256           <para>
3257             Noted that newer dpkg versions do not require extreme care in
3258             always creating the shared lib before the symlink, so the
3259             unpack order be correct
3260           </para>
3261         </listitem>
3262       </varlistentry>
3263     </variablelist>
3264   </section>
3265
3266   <section id="s-3.1.1.0">
3267     <title>Version 3.1.1</title>
3268
3269     <para>
3270       Released November, 1999.
3271     </para>
3272
3273     <variablelist>
3274       <varlistentry>
3275         <term>7.1</term>
3276         <listitem>
3277           <para>
3278             Correction to semantics of architecture lists in Build-Depends
3279             etc.  Should not affect many packages
3280           </para>
3281         </listitem>
3282       </varlistentry>
3283     </variablelist>
3284   </section>
3285
3286   <section id="s-3.1.0.0">
3287     <title>Version 3.1.0</title>
3288
3289     <para>
3290       Released October, 1999.
3291     </para>
3292
3293     <variablelist>
3294       <varlistentry>
3295         <term>defunct</term>
3296         <listitem>
3297           <para>
3298             <filename>/usr/doc/&lt;package&gt;</filename> has to be a
3299             symlink pointing to
3300             <filename>/usr/share/doc/&lt;package&gt;</filename>, to be
3301             maintained by postinst and prerm scripts.
3302           </para>
3303         </listitem>
3304       </varlistentry>
3305       <varlistentry>
3306         <term>7.1, 7.6</term>
3307         <listitem>
3308           <para>
3309             Introduced source dependencies (Build-Depends, etc.)
3310           </para>
3311         </listitem>
3312       </varlistentry>
3313       <varlistentry>
3314         <term>9.3.4</term>
3315         <listitem>
3316           <para>
3317             <filename>/etc/rc.boot</filename> has been deprecated in
3318             favour of <filename>/etc/rcS.d</filename>.  (Packages should
3319             not be touching this directory, but should use update-rc.d
3320             instead)
3321           </para>
3322         </listitem>
3323       </varlistentry>
3324       <varlistentry>
3325         <term>9.3.3</term>
3326         <listitem>
3327           <para>
3328             update-rc.d is now the <emphasis>only</emphasis> allowable way
3329             of accessing the <filename>/etc/rc?.d/[SK]??*</filename>
3330             links.  Any scripts which manipulate them directly must be
3331             changed to use update-rc.d instead.  (This is because the
3332             file-rc package handles this information in an incompatible
3333             way.)
3334           </para>
3335         </listitem>
3336       </varlistentry>
3337       <varlistentry>
3338         <term>12.7</term>
3339         <listitem>
3340           <para>
3341             Architecture-specific examples go in
3342             <filename>/usr/lib/&lt;package&gt;/examples</filename> with
3343             symlinks from
3344             <filename>/usr/share/doc/&lt;package&gt;/examples/*</filename>
3345             or from
3346             <filename>/usr/share/doc/&lt;package&gt;/examples</filename>
3347             itself
3348           </para>
3349         </listitem>
3350       </varlistentry>
3351       <varlistentry>
3352         <term>9.1.1</term>
3353         <listitem>
3354           <para>
3355             Updated FHS to a 2.1 draft; this reverts
3356             <filename>/var/state</filename> to
3357             <filename>/var/lib</filename>
3358           </para>
3359         </listitem>
3360       </varlistentry>
3361       <varlistentry>
3362         <term>9.7; mime-policy</term>
3363         <listitem>
3364           <para>
3365             Added MIME sub-policy document
3366           </para>
3367         </listitem>
3368       </varlistentry>
3369       <varlistentry>
3370         <term>12.4</term>
3371         <listitem>
3372           <para>
3373             VISUAL is allowed as a (higher priority) alternative to EDITOR
3374           </para>
3375         </listitem>
3376       </varlistentry>
3377       <varlistentry>
3378         <term>11.6</term>
3379         <listitem>
3380           <para>
3381             Modified liblockfile description, which affects
3382             mailbox-accessing programs.  Please see the policy document
3383             for details
3384           </para>
3385         </listitem>
3386       </varlistentry>
3387       <varlistentry>
3388         <term>12.7</term>
3389         <listitem>
3390           <para>
3391             If a package provides a changelog in HTML format, a text-only
3392             version should also be included.  (Such a version may be
3393             prepared using <command>lynx -dump -nolist</command>.)
3394           </para>
3395         </listitem>
3396       </varlistentry>
3397       <varlistentry>
3398         <term>3.2.1</term>
3399         <listitem>
3400           <para>
3401             Description of how to handle version numbers based on dates added
3402           </para>
3403         </listitem>
3404       </varlistentry>
3405     </variablelist>
3406   </section>
3407
3408   <section id="s-3.0.1.0">
3409     <title>Version 3.0.1</title>
3410
3411     <para>
3412       Released July, 1999.
3413     </para>
3414
3415     <variablelist>
3416       <varlistentry>
3417         <term>10.2</term>
3418         <listitem>
3419           <para>
3420             Added the clarification that the .la files are essential for
3421             the packages using libtool's libltdl library, in which case
3422             the .la files must go in the run-time library package
3423           </para>
3424         </listitem>
3425       </varlistentry>
3426     </variablelist>
3427   </section>
3428
3429   <section id="s-3.0.0.0">
3430     <title>Version 3.0.0</title>
3431
3432     <para>
3433       Released June, 1999.
3434     </para>
3435
3436     <variablelist>
3437       <varlistentry>
3438         <term>9.1</term>
3439         <listitem>
3440           <para>
3441             Debian formally moves from the FSSTND to the FHS.  This is a
3442             major change, and the implications of this move are probably
3443             not all known.
3444           </para>
3445         </listitem>
3446       </varlistentry>
3447       <varlistentry>
3448         <term>4.1</term>
3449         <listitem>
3450           <para>
3451             Only 3 digits of the Standards version need be included in
3452             control files, though all four digits are still permitted.
3453           </para>
3454         </listitem>
3455       </varlistentry>
3456       <varlistentry>
3457         <term>12.6</term>
3458         <listitem>
3459           <para>
3460             The location of the GPL has changed to
3461             <filename>/usr/share/common-licenses</filename>.  This may
3462             require changing the copyright files to point to the correct
3463             location of the GPL and other major licenses
3464           </para>
3465         </listitem>
3466       </varlistentry>
3467       <varlistentry>
3468         <term>10.2</term>
3469         <listitem>
3470           <para>
3471             Packages that use libtool to create shared libraries must
3472             include the .la files in the -dev packages
3473           </para>
3474         </listitem>
3475       </varlistentry>
3476       <varlistentry>
3477         <term>10.8</term>
3478         <listitem>
3479           <para>
3480             Use logrotate to rotate log files
3481           </para>
3482         </listitem>
3483       </varlistentry>
3484       <varlistentry>
3485         <term>now 11.8</term>
3486         <listitem>
3487           <para>
3488             section 5.8 has been rewritten (Programs for the X Window System)
3489           </para>
3490         </listitem>
3491       </varlistentry>
3492       <varlistentry>
3493         <term>9.6; menu-policy</term>
3494         <listitem>
3495           <para>
3496             There is now an associated menu policy, in a separate
3497             document, that carries the full weight of Debian policy
3498           </para>
3499         </listitem>
3500       </varlistentry>
3501       <varlistentry>
3502         <term>11.3</term>
3503         <listitem>
3504           <para>
3505             Programs which need to modify the files
3506             <filename>/var/run/utmp</filename>,
3507             <filename>/var/log/wtmp</filename> and
3508             <filename>/var/log/lastlog</filename> must be installed setgid
3509             utmp
3510           </para>
3511         </listitem>
3512       </varlistentry>
3513     </variablelist>
3514   </section>
3515
3516   <section id="s-2.5.0.0">
3517     <title>Version 2.5.0</title>
3518
3519     <para>
3520       Released October, 1998.
3521     </para>
3522     <para>
3523       <emphasis>Please note that section numbers below this point may not
3524       match the current Policy Manual.</emphasis>
3525     </para>
3526
3527     <itemizedlist>
3528       <listitem>
3529         <para>
3530           Rearranged the manual to create a new Section 4, Files
3531         </para>
3532         <itemizedlist>
3533           <listitem>
3534             <para>
3535               Section 3.3 ("Files") was moved to Section 4.  The Sections
3536               that were Section 4 and Section 5 were moved down to become
3537               Section 5 and Section 6.
3538             </para>
3539           </listitem>
3540           <listitem>
3541             <para>
3542               What was Section 5.5 ("Log files") is now a subsection of
3543               the new Section 4 ("Files"), becoming section 4.8, placed
3544               after "Configuration files", moving the Section 4.8
3545               ("Permissions and owners") to Section 4.9.  All subsections
3546               of the old Section 5 after 5.5 were moved down to fill in
3547               the number gap.
3548             </para>
3549           </listitem>
3550         </itemizedlist>
3551       </listitem>
3552       <listitem>
3553         <para>
3554           Modified the section about changelog files to accommodate
3555           upstream changelogs which were formatted as HTML.  These
3556           upstream changelog files should now be accessible as
3557           <filename>/usr/doc/package/changelog.html.gz</filename>
3558         </para>
3559       </listitem>
3560       <listitem>
3561         <para>
3562           Symlinks are permissible to link the real, or upstream,
3563           changelog name to the Debian mandated name.
3564         </para>
3565       </listitem>
3566       <listitem>
3567         <para>
3568           Clarified that HTML documentation should be present in some
3569           package, though not necessarily the main binary package.
3570         </para>
3571       </listitem>
3572       <listitem>
3573         <para>
3574           Corrected all references to the location of the copyright files.
3575           The correct location is
3576           <filename>/usr/doc/package/copyright</filename>
3577         </para>
3578       </listitem>
3579       <listitem>
3580         <para>
3581           Ratified the architecture specification strings to cater to the
3582           HURD.
3583         </para>
3584       </listitem>
3585     </itemizedlist>
3586   </section>
3587
3588   <section id="s-2.4.1.0">
3589     <title>Version 2.4.1</title>
3590
3591     <para>
3592       Released April, 1998.
3593     </para>
3594
3595     <variablelist>
3596       <varlistentry>
3597         <term>Updated section 3.3.5 Symbolic links</term>
3598         <listitem>
3599           <para>
3600             symbolic links within a toplevel directory should be
3601             relative, symbolic links between toplevel directories should
3602             be absolute (cf., Policy Weekly Issue#6, topic 2)
3603           </para>
3604         </listitem>
3605       </varlistentry>
3606       <varlistentry>
3607         <term>Updated section 4.9 Games</term>
3608         <listitem>
3609           <para>
3610             manpages for games should be installed in
3611             <filename>/usr/man/man6</filename> (cf., Policy Weekly
3612             Issue#6, topic 3)
3613           </para>
3614         </listitem>
3615       </varlistentry>
3616       <varlistentry>
3617         <term>Updated Chapter 12 Shared Libraries</term>
3618         <listitem>
3619           <para>
3620             ldconfig must be called in the postinst script if the package
3621             installs shared libraries (cf., Policy Weekly Issue #6,
3622             fixes:bug#20515)
3623           </para>
3624         </listitem>
3625       </varlistentry>
3626     </variablelist>
3627   </section>
3628
3629   <section id="s-2.4.0.0">
3630     <title>Version 2.4.0</title>
3631
3632     <para>
3633       Released January, 1998
3634     </para>
3635
3636     <variablelist>
3637       <varlistentry>
3638         <term>Updated section 3.3.4 Scripts</term>
3639         <listitem>
3640           <itemizedlist>
3641             <listitem>
3642               <para>
3643                 /bin/sh may be any POSIX compatible shell
3644               </para>
3645             </listitem>
3646             <listitem>
3647               <para>
3648                 scripts including bashisms have to specify
3649                 <filename>/bin/bash</filename> as interpreter
3650               </para>
3651             </listitem>
3652             <listitem>
3653               <para>
3654                 scripts which create files in world-writable directories
3655                 (e.g., in <filename>/tmp</filename>) should use tempfile
3656                 or mktemp for creating the directory
3657               </para>
3658             </listitem>
3659           </itemizedlist>
3660         </listitem>
3661       </varlistentry>
3662       <varlistentry>
3663         <term>Updated section 3.3.5 Symbolic Links</term>
3664         <listitem>
3665           <para>
3666             symbolic links referencing compressed files must have the same
3667             file extension as the referenced file
3668           </para>
3669         </listitem>
3670       </varlistentry>
3671       <varlistentry>
3672         <term>Updated section 3.3.6 Device files</term>
3673         <listitem>
3674           <para>
3675             <filename>/dev/tty*</filename> serial devices should be used
3676             instead of <filename>/dev/cu*</filename>
3677           </para>
3678         </listitem>
3679       </varlistentry>
3680       <varlistentry>
3681         <term>
3682           Updated section 3.4.2 Writing the scripts in
3683           <filename>/etc/init.d</filename>
3684         </term>
3685         <listitem>
3686           <itemizedlist>
3687             <listitem>
3688               <para>
3689                 all <filename>/etc/init.d</filename> scripts have to
3690                 provide the following options: start, stop, restart,
3691                 force-reload
3692               </para>
3693             </listitem>
3694             <listitem>
3695               <para>
3696                 the reload option is optional and must never stop and
3697                 restart the service
3698               </para>
3699             </listitem>
3700           </itemizedlist>
3701         </listitem>
3702       </varlistentry>
3703       <varlistentry>
3704         <term>Updated section 3.5 Cron jobs</term>
3705         <listitem>
3706           <para>
3707             cron jobs that need to be executed more often than daily
3708             should be installed into <filename>/etc/cron.d</filename>
3709           </para>
3710         </listitem>
3711       </varlistentry>
3712       <varlistentry>
3713         <term>Updated section 3.7 Menus</term>
3714         <listitem>
3715           <para>
3716             removed section about how to register HTML docs to `menu' (the
3717             corresponding section in 4.4, Web servers and applications,
3718             has been removed in policy 2.2.0.0 already, so this one was
3719             obsolete)
3720           </para>
3721         </listitem>
3722       </varlistentry>
3723       <varlistentry>
3724         <term>New section 3.8 Keyboard configuration</term>
3725         <listitem>
3726           <para>
3727             details about how the backspace and delete keys should be
3728             handled
3729           </para>
3730         </listitem>
3731       </varlistentry>
3732       <varlistentry>
3733         <term>New section 3.9 Environment variables</term>
3734         <listitem>
3735           <para>
3736             no program must depend on environment variables to get a
3737             reasonable default configuration
3738           </para>
3739         </listitem>
3740       </varlistentry>
3741       <varlistentry>
3742         <term>New section 4.6 News system configuration</term>
3743         <listitem>
3744           <para>
3745             <filename>/etc/news/organization</filename> and
3746             <filename>/etc/news/server</filename> should be supported by
3747             all news servers and clients
3748           </para>
3749         </listitem>
3750       </varlistentry>
3751       <varlistentry>
3752         <term>Updated section 4.7 Programs for the X Window System</term>
3753         <listitem>
3754           <itemizedlist>
3755             <listitem>
3756               <para>
3757                 programs requiring a non-free Motif library should be
3758                 provided as foo-smotif and foo-dmotif package
3759               </para>
3760             </listitem>
3761             <listitem>
3762               <para>
3763                 if lesstif works reliably for such program, it should be
3764                 linked against lesstif and not against a non-free Motif
3765                 library
3766               </para>
3767             </listitem>
3768           </itemizedlist>
3769         </listitem>
3770       </varlistentry>
3771       <varlistentry>
3772         <term>Updated section 4.9 Games</term>
3773         <listitem>
3774           <para>
3775             games for X Windows have to be installed in
3776             <filename>/usr/games</filename>, just as non-X games
3777           </para>
3778         </listitem>
3779       </varlistentry>
3780     </variablelist>
3781   </section>
3782
3783   <section id="s-2.3.0.0">
3784     <title>Version 2.3.0</title>
3785
3786     <para>
3787       Released September, 1997.
3788     </para>
3789
3790     <itemizedlist>
3791       <listitem>
3792         <para>
3793           new section `4.2 Daemons' including rules for
3794           <filename>/etc/services</filename>,
3795           <filename>/etc/protocols</filename>,
3796           <filename>/etc/rpc</filename>, and
3797           <filename>/etc/inetd.conf</filename>
3798         </para>
3799       </listitem>
3800       <listitem>
3801         <para>
3802           updated section about `Configuration files': packages may not
3803           touch other packages' configuration files
3804         </para>
3805       </listitem>
3806       <listitem>
3807         <para>
3808           MUAs and MTAs have to use liblockfile
3809         </para>
3810       </listitem>
3811     </itemizedlist>
3812   </section>
3813
3814   <section id="s-2.2.0.0">
3815     <title>Version 2.2.0</title>
3816
3817     <para>
3818       Released July, 1997.
3819     </para>
3820
3821     <itemizedlist>
3822       <listitem>
3823         <para>
3824           added section 4.1 `Architecture specification strings': use
3825           &lt;arch&gt;-linux where &lt;arch&gt; is one of the following:
3826           i386, alpha, arm, m68k, powerpc, sparc.
3827         </para>
3828       </listitem>
3829       <listitem>
3830         <para>
3831           detailed rules for <filename>/usr/local</filename>
3832         </para>
3833       </listitem>
3834       <listitem>
3835         <para>
3836           user ID's
3837         </para>
3838       </listitem>
3839       <listitem>
3840         <para>
3841           editor/pager policy
3842         </para>
3843       </listitem>
3844       <listitem>
3845         <para>
3846           cron jobs
3847         </para>
3848       </listitem>
3849       <listitem>
3850         <para>
3851           device files
3852         </para>
3853       </listitem>
3854       <listitem>
3855         <para>
3856           don't install shared libraries as executable
3857         </para>
3858       </listitem>
3859       <listitem>
3860         <para>
3861           app-defaults files may not be conffiles
3862         </para>
3863       </listitem>
3864     </itemizedlist>
3865   </section>
3866
3867   <section id="s-2.1.3.0">
3868     <title>Version 2.1.3</title>
3869
3870     <para>
3871       Released March, 1997.
3872     </para>
3873
3874     <itemizedlist>
3875       <listitem>
3876         <para>
3877           two programs with different functionality must not have the same
3878           name
3879         </para>
3880       </listitem>
3881       <listitem>
3882         <para>
3883           "Webstandard 3.0"
3884         </para>
3885       </listitem>
3886       <listitem>
3887         <para>
3888           "Standard for Console Messages"
3889         </para>
3890       </listitem>
3891       <listitem>
3892         <para>
3893           Libraries should be compiled with `-D_REENTRANT'
3894         </para>
3895       </listitem>
3896       <listitem>
3897         <para>
3898           Libraries should be stripped with <command>strip
3899           --strip-unneeded</command>
3900         </para>
3901       </listitem>
3902     </itemizedlist>
3903   </section>
3904
3905   <section id="s-2.1.2.0">
3906     <title>Version 2.1.2</title>
3907
3908     <para>
3909       Released November, 1996.
3910     </para>
3911
3912     <itemizedlist>
3913       <listitem>
3914         <para>
3915           Some changes WRT shared libraries
3916         </para>
3917       </listitem>
3918     </itemizedlist>
3919   </section>
3920
3921   <section id="s-2.1.1.0">
3922     <title>Version 2.1.1</title>
3923
3924     <para>
3925       Released September, 1996.
3926     </para>
3927
3928     <itemizedlist>
3929       <listitem>
3930         <para>
3931           No hard links in source packages
3932         </para>
3933       </listitem>
3934       <listitem>
3935         <para>
3936           Do not use <command>dpkg-divert</command> or
3937           <command>update-alternatives</command> without consultation
3938         </para>
3939       </listitem>
3940       <listitem>
3941         <para>
3942           Shared libraries must be installed stripped
3943         </para>
3944       </listitem>
3945     </itemizedlist>
3946   </section>
3947
3948   <section id="s-2.1.0.0">
3949     <title>Version 2.1.0</title>
3950
3951     <para>
3952       Released August, 1996.
3953     </para>
3954
3955     <itemizedlist>
3956       <listitem>
3957         <para>
3958           Upstream changelog must be installed too
3959         </para>
3960       </listitem>
3961     </itemizedlist>
3962   </section>
3963 </appendix>