upgrading-checklist.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3   <head>
   4  <!--                             -*- Mode: Sgml -*-
   5     upgrading-checklist.html
   6     Author           : Manoj Srivastava ( srivasta@tiamat.datasync.com )
   7     Created On       : Thu Oct 29 20:54:48 1998
   8     Created On Node  : tiamat.datasync.com
   9     Last Modified By : Manoj Srivastava
  10     Last Modified On : Sat Apr 28 13:36:28 2001
  11     Last Machine Used: glaurung.green-gryphon.com
  12     Update Count     : 16
  13     Status           : Unknown, Use with caution!
  14     HISTORY          :
  15     Description      :
  16
  17     -->
  18
  19
  20     <title>Policy checklist for upgrading your packages</title>
  21   </head>
  22   <body>
  23
  24     <h1>Policy checklist for upgrading your packages</h1>
  25
  26     <h2>About the checklist</h2>
  27
  28 <p>
  29 The checklist below has been created to simplify the upgrading process
  30 of old packages.  Note that this list is not `official'; it simply
  31 gives an indication of what has changed and whether you are likely to
  32 need to make changes to your package in light of this.  If you have
  33 doubts about a certain topic, if you need more details, or if you
  34 think some other package does not comply with policy, please refer to
  35 the Policy Manual itself.  All of the changes from version 3.0.0
  36 onwards indicate which section of the Policy Manual discusses the
  37 issue: [3.4] means section 3.4.  The section numbering changed when
  38 the packaging manual was incorporated into policy; the section numbers
  39 used below refer to the current version.
  40 </p>
  41
  42 <p>
  43 Here is how the check list works: Check which policy version your
  44 package complies with currently (indicated in the "Standards-Version"
  45 field of the source package).  Then move upwards until the top and
  46 check which of the items on the list might concern your package.  Note
  47 which sections of policy discuss this, and then check out the Policy
  48 Manual for details.  If you are upgrading from Policy version < 2.5.0,
  49 it may be easier to check through the whole of policy instead of
  50 picking your way through this list.
  51 </p>
  52
  53 <h2>The checklist</h2>
  54
  55 <pre>
  56 3.5.5.0                    May 01
  57
  58      - [Clarified note in 3.5.3.0 upgrading checklist regarding
  59         examples and templates: this refers only to those examples used
  60         by scripts; see section 11.7.3 for the whole story]
  61      - Included a new section 11.9.1 describing the use of
  62        dpkg-statoverride; this does not have the weight of policy
  63
  64
  65 3.5.4.0                    Apr 01
  66
  67      - The system-wide mail directory is now /var/mail, no longer
  68        /var/spool/mail.  Any packages accessing the mail spool should
  69        access it via /var/mail and include a suitable Depends field;
  70        details in [12.6]
  71      - The perl policy is now part of Debian policy proper. Perl
  72        programs and modules should follow the current Perl policy
  73        [12.9; perl-policy]
  74
  75
  76 3.5.3.0                    Apr 01
  77
  78      - Build-Depends arch syntax has been changed to be less
  79        ambiguous. This should not affect any current packages [7.1]
  80      - Examples and templates files for use by scripts should now live
  81        in /usr/share/&lt;package&gt; or /usr/lib/&lt;package&gt;, with
  82        symbolic links from /usr/share/doc//&lt;package&gt;/examples as
  83        needed [11.7.3]
  84
  85
  86 3.5.2.0                    Feb 01
  87
  88      - X app-defaults directory has moved from
  89        /usr/X11R6/lib/X11/app-defaults to /etc/X11/app-defaults [12.8]
  90
  91
  92 3.5.1.0                    Feb 01
  93
  94      - dpkg-shlibdeps now uses objdump, so shared libraries have to be
  95        run through dpkg-shlibdeps as well as executables [9.1]
  96
  97
  98 3.5.0.0                    Jan 01
  99
 100      - Font packages for the X Window System must now declare a
 101        dependency on xutils (>= 4.0.2) [12.8]
 102
 103
 104 3.2.1.1                    Jan 01
 105
 106      - Daemon startup scripts in /etc/init.d/ should not contain
 107        modifiable parameters; these should be moved to a file in
 108        /etc/default/; see [10.3.2] for details
 109      - Files in /usr/share/doc must not be referenced by any
 110        program.  If such files are needed, they must be placed in
 111        /usr/share/&lt;package&gt;/, and symbolic links created as required
 112        in /usr/share/doc/&lt;package&gt;/ [13.3]
 113      - Much of the packaging manual has now been imported into the
 114        policy document
 115
 116
 117 3.2.1.0                    Aug 00
 118
 119      - A package of priority standard or higher may provide two
 120        binaries, one compiled with support for the X Window System,
 121        and the other without [12.8]
 122
 123
 124 3.2.0.0                    Aug 00
 125
 126      - By default executables should not be built with the debugging
 127        option -g. Instead, it is recommended to support building the
 128        package with debugging information optionally.  Details in [11.1]
 129      - Policy for packages where the upstream uses HTML changelog
 130        files has been expanded.  In short, a plain text changelog file
 131        should always be generated for the upstream changes [13.8]
 132      - Please note that the new release of the X window system (4.x)
 133        shall probably need sweeping changes in policy
 134      - Policy for packages providing the following X-based features
 135        has been codified [12.8]:
 136        - X server (virtual package xserver)
 137        - X terminal emulator (virtual package x-terminal-emulator)
 138        - X window manager (virtual package x-window-manager, and
 139          /usr/bin/x-window-manager alternative, with priority
 140          calculation guidelines)
 141        - X fonts (this section has been written from scratch)
 142        - X application defaults
 143      - Policy for packages using the X Window System and FHS issues
 144        has been clarified; see [12.8]
 145      - No package may contain or make hard links to conffiles [11.7.3]
 146      - Noted that newer dpkg versions do not require extreme care in
 147        always creating the shared lib before the symlink, so the unpack
 148        order be correct [9]
 149
 150
 151 3.1.1.0                    Nov 99
 152
 153      - Correction to semantics of architecture lists in Build-Depends
 154        etc.  Should not affect many packages [7.1]
 155
 156
 157 3.1.0.0                    Oct 99
 158
 159      - /usr/doc/&lt;package&gt; has to be a symlink pointing to
 160        /usr/share/doc/&lt;package&gt;, to be maintained by postinst
 161        and prerm scripts.  Details are in [13.4]
 162      - Introduced source dependencies (Build-Depends, etc.) [7.1, 7.6]
 163      - /etc/rc.boot has been deprecated in favour of /etc/rcS.d.
 164        (Packages should not be touching this directory, but should use
 165        update-rc.d instead) [10.3.4]
 166      - update-rc.d is now the *only* allowable way of accessing the
 167        /etc/rc?.d/[SK]??* links.  Any scripts which manipulate them
 168        directly must be changed to use update-rc.d instead.  (This is
 169        because the file-rc package handles this information in an
 170        incompatible way.) [10.3.3]
 171      - Architecture-specific examples go in /usr/lib/&lt;package&gt;/examples
 172        with symlinks from /usr/share/doc/&lt;package&gt;/examples/* or from
 173        /usr/share/doc/&lt;package&gt;/examples itself [13.7]
 174      - Updated FHS to a 2.1 draft; this reverts /var/state to
 175        /var/lib [10.1.1]
 176      - Added MIME sub-policy document [10.7; mime-policy]
 177      - VISUAL is allowed as a (higher priority) alternative to EDITOR [12.4]
 178      - Modified liblockfile description, which affects
 179        mailbox-accessing programs.  Please see the policy document for
 180        details [12.6]
 181      - If a package provides a changelog in HTML format, a text-only
 182        version should also be included.  (Such a version may be prepared
 183        using lynx -dump -nolist.) [13.8]
 184      - Description of how to handle version numbers based on dates
 185        added [4.1]
 186
 187
 188 3.0.1.0                    Jul 99
 189
 190     -  Added the clarification that the .la files are essential for the
 191        packages using libtool's libltdl library, in which case the
 192        .la files must go in the run-time library package [11.2]
 193
 194
 195 3.0.0.0                    Jun 99
 196
 197     - Debian formally moves from the FSSTND to the FHS. This is a
 198       major change, and the implications of this move are probably
 199       not all known. [10.1]
 200     - Only 3 digits of the Standards version need be included in
 201       control files, though all four digits are still permitted. [2.4.1]
 202     - The location of the GPL has changed to
 203       /usr/share/common-licenses. This may require changing the
 204       copyright files to point to the correct location of the GPL and
 205       other major licenses [13.6]
 206     - Packages that use libtool to create shared libraries must
 207       include the .la files in the -dev packages [11.2]
 208     - Use logrotate to rotate log files [11.8]
 209     - section 5.8 has been rewritten (Programs for the X Window
 210       System) [now 12.8]
 211     - There is now an associated menu policy, in a separate document,
 212       that carries the full weight of Debian policy [10.6; menu-policy]
 213     - Programs which need to modify the files /var/run/utmp,
 214       /var/log/wtmp and /var/log/lastlog must be installed setgid utmp [12.3]
 215
 216
 217 2.5.0.0                         Oct 98
 218
 219   Policy Manual:
 220     - Rearranged the manual to create a new Section 4, Files
 221       + Section 3.3 ("Files") was moved to Section 4. The Sections
 222         that  were Section 4 and Section 5 were  moved down to become
 223         Section 5 and Section 6.
 224       + What was Section 5.5 ("Log files") is now a subsection of the
 225         new Section 4 ("Files"), becoming section 4.8, placed after
 226         "Configuration files", moving the Section 4.8 ("Permissions
 227         and owners") to Section 4.9.  All subsections of the old
 228         Section 5 after 5.5  were moved down to fill in the number
 229         gap.
 230     - Modified the section about changelog files to accommodate
 231       upstream changelogs which were formatted as HTML/ These
 232       upstream changelog files should now be accessible as
 233       /usr/doc/package/changelog.html.gz
 234       + Symlinks are permissible to link the real, or upstream,
 235         changelog name to the Debian mandated name.
 236     - Clarified that HTML documentation should be present in some
 237       package, though not necessarily the main binary package.
 238     - Corrected all references to the location of the copyright
 239       files. The correct location is /usr/doc/package/copyright
 240     - Ratified the architecture specification strings to cater to the
 241       HURD.
 242
 243 2.4.1.0                         Apr 98
 244
 245   Policy Manual:
 246     - Updated section 3.3.5 Symbolic links:
 247       + symbolic links within a toplevel directory should be relative,
 248         symbolic links between toplevel directories should be absolute
 249         (cf., Policy Weekly Issue#6, topic 2)
 250
 251     - Updated section 4.9 Games:
 252       + manpages for games should be installed in /usr/man/man6
 253         (cf., Policy Weekly Issue#6, topic 3)
 254
 255   Packaging Manual:
 256     - Updated prefix of chapter 12, Shared Libraries:
 257       ldconfig must be called in the postinst script if the package
 258       installs shared libraries
 259       (cf., Policy Weekly Issue #6, fixes:bug#20515)
 260
 261 2.4.0.0                         Jan 98
 262
 263     - Updated section 3.3.4 Scripts:
 264       + /bin/sh may be any POSIX compatible shell
 265       + scripts including bashisms have to specify /bin/bash as
 266         interpreter
 267       + scripts which create files in world-writable directories
 268         (e.g., in /tmp) should use tempfile or mktemp for creating
 269         the directory
 270
 271     - Updated section 3.3.5 Symbolic Links:
 272       + symbolic links referencing compressed files must have the same
 273         file extension as the referenced file
 274
 275     - Updated section 3.3.6 Device files:
 276       + /dev/tty* serial devices should be used instead of /dev/cu*
 277
 278     - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
 279       + all /etc/init.d scripts have to provide the following options:
 280         start, stop, restart, force-reload
 281       + the reload option is optional and must never stop and restart
 282         the service
 283
 284     - Updated section 3.5 Cron jobs:
 285       + cron jobs that need to be executed more often than daily should
 286         be installed into /etc/cron.d
 287
 288     - Updated section 3.7 Menus:
 289       + removed section about how to register HTML docs to `menu'
 290         (the corresponding section in 4.4, Web servers and applications,
 291         has been removed in policy 2.2.0.0 already, so this one was
 292         obsolete)
 293
 294     - New section 3.8 Keyboard configuration:
 295       + details about how the backspace and delete keys should be
 296         handled
 297
 298     - New section 3.9 Environment variables:
 299       + no program must depend on environment variables to get a
 300         reasonable default configuration
 301
 302     - New section 4.6 News system configuration:
 303       + /etc/news/organization and /etc/news/server should be supported
 304         by all news servers and clients
 305
 306     - Updated section 4.7 Programs for the X Windows system:
 307       + programs requiring a non-free Motif library should be provided
 308         as foo-smotif and foo-dmotif package
 309       + if lesstif works reliably for such program, it should be linked
 310         against lesstif and not against a non-free Motif library
 311
 312     - Updated section 4.9 Games:
 313       + games for X Windows have to be installed in /usr/games, just as
 314         non-X games
 315
 316 2.3.0.1, 2.3.0.0                Sep 97
 317
 318         * new section `4.2 Daemons' including rules for
 319           /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
 320
 321         * updated section about `Configuration files':
 322           packages may not touch other packages' configuration files
 323
 324         * MUAs and MTAs have to use liblockfile
 325
 326 2.2.0.0                         Jul 97
 327
 328         * added section 4.1 `Architecture specification strings':
 329           use
 330                &lt;arch&gt;-linux
 331           where &lt;arch&gt; is one of the following:
 332                i386, alpha, arm, m68k, powerpc, sparc.
 333
 334         * detailed rules for /usr/local
 335
 336         * user ID's
 337
 338         * editor/pager policy
 339
 340         * cron jobs
 341
 342         * device files
 343
 344         * don't install shared libraries as executable
 345
 346         * app-defaults files may not be conffiles
 347
 348 2.1.3.2, 2.1.3.1, 2.1.3.0       Mar 97
 349
 350         * two programs with different functionality must not have the
 351           same name
 352
 353         * "Webstandard 3.0"
 354
 355         * "Standard for Console Messages"
 356
 357         * Libraries should be compiled with `-D_REENTRANT'
 358
 359         * Libraries should be stripped with "strip --strip-unneeded"
 360
 361 2.1.2.2, 2.1.2.1, 2.1.2.0       Nov 96
 362
 363         * Some changes WRT shared libraries
 364
 365 2.1.1.0                         Sep 96
 366
 367         * No hard links in source packages
 368
 369         * Do not use dpkg-divert or update-alternatives without consultation
 370
 371         * Shared libraries must be installed stripped
 372
 373 2.1.0.0                         Aug 96
 374
 375         * Upstream changelog must be installed too
 376 </pre>
 377
 378     <hr>
 379
 380   </body>
 381 </html>
 382
 383 <!-- Keep this comment at the end of the file
 384 Local variables:
 385 mode: sgml
 386 sgml-indent-data: t
 387 sgml-live-element-indicator: t
 388 sgml-set-face: t
 389 End:
 390 -->