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