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 : Julian Gilbey
  10     Last Modified On : Mon Jun 19 20:06:50 2000
  11     Last Machine Used: polya.maths.qmw.ac.uk
  12     Update Count     : 11
  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.' If you have
  31 doubts about a certain topic, if you need more details, or if you
  32 think some other package does not comply with policy, please refer to
  33 the Policy Manual.
  34 </p>
  35
  36 <p>
  37 Here is how the check list works: Check out which policy version your
  38 packages complies with currently. Than move upwards until the top and
  39 check which of the items on the list might concern your package. If an
  40 item does not give you enough details, please check out the Policy
  41 Manual.
  42 </p>
  43
  44 <h2>The checklist</h2>
  45
  46 <pre>
  47 3.2.0.0                    Aug 00
  48
  49   Policy Manual:
  50      - By default executables should not be built with the debugging
  51        option -g. Instead, it is recommended to support building the
  52        package with debugging information optionally.
  53      - Policy for packages where the upstream uses html changelog
  54        files has been expanded. In short, a plain text changelog file
  55        should always be generated for the upstream changes.
  56      - Please note that the new release of the X window system (4.x)
  57        shall probably need sweeping changes in policy.
  58      - Policy for packages providing an X server has been codified
  59        (formalizes existing practice - use virtual package xserver)
  60      - Policy for packages providing an X terminal emulator has been
  61        codified (use virtual package x-terminal-emulator)
  62      - Policy for packages providing an X window manager has been
  63        codified (use virtual package x-window-anager, and also as an
  64        alternative for /usr/bin/x-window-manager. The policy has
  65        guidelines on how to calculate priority)
  66      - Policy for packages providing an X fonts has been
  67        codified. Please look into the manual for details; this section
  68        has been written from scratch.
  69      - Policy for packages using the X Window System and FHS issues
  70        has been clarified. Please read the manual for details.
  71      - Policy for packages providing an X application default has been
  72        clarified.
  73      - No package may contain or make hard links to conffiles.
  74
  75   Packaging Manual:
  76      - Noted that newer dpkg versions do not require extreme care in
  77        always creating theshared lib before the symlink, so the unpack
  78        order be correct.
  79      - Note that the newer dpkg-shlibdeps use objdump to determine the
  80        shared libraries directly, and now should be run on both
  81        executables and libraries.
  82
  83 3.1.1.0                    Nov 99
  84
  85   Packaging Manual:
  86      - Correction to semantics of architecture lists in Build-Depends
  87       etc.  Should not affect many packages.
  88
  89 3.1.0.0                    Oct 99
  90
  91   Policy Manual:
  92      - /usr/doc/&lt;package&gt; has to be a symlink pointing to
  93        /usr/share/doc/&lt;package&gt;.  This symlink has to be
  94        maintained by postinst and prerm, because dpkg will cause
  95        problems otherwise.  Create/remote the symlinks using debhelper
  96        or see section "6.4. Accessing the documentation" for more
  97        information.
  98      - Introduced source dependencies.  (Whereas this ought to demand a
  99        major policy number rise, we've only just had one of them, so
 100        I'm going to use a minor number instead.)
 101      - /etc/rc.boot has been deprecated in favour of /etc/rcS.d.
 102        Packages should not be touching this directory, anyway, but
 103        should use update-rc.d instead.
 104      - update-rc.d is now the *only* allowable way of accessing the
 105        /etc/rc?.d/[SK]??* links.  Any scripts which manipulate them
 106        directly must be changed to use update-rc.d instead.  (This is
 107        because the file-rc package handles this information in an
 108        incompatible way.)
 109      - Compiled examples go in /usr/lib/&lt;package&gt;/examples with
 110        symlinks from /usr/share/doc/&lt;package&gt;/examples/* or from
 111        /usr/share/doc/&lt;package&gt;/examples itself.
 112      - Updated FHS to a 2.1 draft; this reverts /var/state to
 113       /var/lib.
 114      - Added MIME sub-policy document.
 115      - VISUAL is allowed as a (higher priority) alternative to EDITOR.
 116      - Modified liblockfile description, which affects
 117        mailbox-accessing programs.  Please see the policy document for
 118        details.
 119      - If a package provides a changelog in HTML format, a text-only
 120        version should also be included.  Such a version may be prepared
 121        using lynx -dump -nolist.)
 122
 123   Packaging Manual:
 124      - Description of how to handle version numbers based on dates
 125        added: see section 5.1.
 126
 127
 128 3.0.1.0                    Jul 99
 129
 130   Policy Manual:
 131     -  Added the clarification that the .la files are essential for the
 132        packages using libtool's libltdl library, in which case the
 133        .la files must go in the run-time library package.
 134
 135
 136 3.0.0.0                    Jun 99
 137
 138   Policy Manual:
 139     - Debian formally moves from the FSSTND to the FHS. This is a
 140       major change, and the implications of this move are probably
 141       not all known.
 142     - Only 3 digits of the Standards version need be included in
 143       control files, though all four digits are still permitted.
 144     - The location of the GPL has changed to
 145       /usr/share/common-licenses. This may require changing the
 146       copyright files to point to the correct location of the GPL and
 147       other major licences
 148     - Packages that use libtool to create shared libraries must
 149       include the .la files in the -dev packages.
 150     - Use logrotate to rotate log files
 151     - section 5.8 has been rewritten (Programs for the X Window
 152       System)
 153     - There is now anassi=ociated menu policy, in a separate document,
 154       that carries the full weight of Debian policy.
 155     - The files `/var/run/utmp', `/var/log/wtmp' and
 156       `/var/log/lastlog' must be installed writeable by group
 157       utmp. Programs who need to modify those files must be installed
 158       install setgid utmp.
 159
 160
 161 2.5.0.0                         Oct 98
 162
 163   Policy Manual:
 164     - Rearranged the manual to create a new Section 4, Files
 165       + Section 3.3 ("Files") was moved to Section 4. The Sections
 166         that  were Section 4 and Section 5 were  moved down to become
 167         Section 5 and Section 6.
 168       + What was Section 5.5 ("Log files") is now a subsection of the
 169         new Section 4 ("Files"), becoming section 4.8, placed after
 170         "Configuration files", moving the Section 4.8 ("Permissions
 171         and owners") to Section 4.9.  All subsections of the old
 172         Section 5 after 5.5  were moved down to fill in the number
 173         gap.
 174     - Modified the section about changelog files to accomodate
 175       upstream changelogs which were formatted as HTML/ These
 176       upstream chagelog files should now be accessible as
 177       /usr/doc/package/changelog.html.gz
 178       + Symlinks are permissible to link the real, or upstream,
 179         changelog name to the Debian mandated name.
 180     - Clarified that HTML documentation should be present in some
 181       package, though not necessarily the main binary package.
 182     - Corrected all references to the location of the copyright
 183       files. The correct location is /usr/doc/package/copyright
 184     - Ratified the architecture specification strings to cater to the
 185       HURD.
 186
 187 2.4.1.0                         Apr 98
 188
 189   Policy Manual:
 190     - Updated section 3.3.5 Symbolic links:
 191       + symbolic links within a toplevel directory should be relative,
 192         symbolic links between toplevel directories should be absolute
 193         (cf., Policy Weekly Issue#6, topic 2)
 194
 195     - Updated section 4.9 Games:
 196       + manpages for games should be installed in /usr/man/man6
 197         (cf., Policy Weekly Issue#6, topic 3)
 198
 199   Packaging Manual:
 200     - Updated prefix of chapter 12, Shared Libraries:
 201       ldconfig must be called in the postinst script if the package
 202       installs shared libraries
 203       (cf., Policy Weekly Issue #6, fixes:bug#20515)
 204
 205 2.4.0.0                         Jan 98
 206
 207     - Updated section 3.3.4 Scripts:
 208       + /bin/sh may be any POSIX compatible shell
 209       + scripts including bashisms have to specify /bin/bash as
 210         interpreter
 211       + scripts which create files in world-writable directories
 212         (e.g., in /tmp) should use tempfile or mktemp for creating
 213         the directory
 214
 215     - Updated section 3.3.5 Symbolic Links:
 216       + symbolic links referencing compressed files must have the same
 217         file extension as the referenced file
 218
 219     - Updated section 3.3.6 Device files:
 220       + /dev/tty* serial devices should be used instead of /dev/cu*
 221
 222     - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
 223       + all /etc/init.d scripts have to provide the following options:
 224         start, stop, restart, force-reload
 225       + the reload option is optional and must never stop and restart
 226         the service
 227
 228     - Updated section 3.5 Cron jobs:
 229       + cron jobs that need to be executed more often than daily should
 230         be installed into /etc/cron.d
 231
 232     - Updated section 3.7 Menus:
 233       + removed section about how to register HTML docs to `menu'
 234         (the corresponding section in 4.4, Web servers and applications,
 235         has been removed in policy 2.2.0.0 already, so this one was
 236         obsolete)
 237
 238     - New section 3.8 Keyboard configuration:
 239       + details about how the backspace and delete keys should be
 240         handled
 241
 242     - New section 3.9 Environment variables:
 243       + no program must depend on environment variables to get a
 244         reasonable default configuration
 245
 246     - New section 4.6 News system configuration:
 247       + /etc/news/organization and /etc/news/server should be supported
 248         by all news servers and clients
 249
 250     - Updated section 4.7 Programs for the X Windows system:
 251       + programs requiring a non-free Motif library should be provided
 252         as foo-smotif and foo-dmotif package
 253       + if lesstif works reliably for such program, it should be linked
 254         against lesstif and not against a non-free Motif library
 255
 256     - Updated section 4.9 Games:
 257       + games for X Windows have to be installed in /usr/games, just as
 258         non-X games
 259
 260 2.3.0.1, 2.3.0.0                Sep 97
 261
 262         * new section `4.2 Daemons' including rules for
 263           /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
 264
 265         * updated section about `Configuration files':
 266           packages may not touch other packages' configuration files
 267
 268         * MUAs and MTAs have to use liblockfile
 269
 270 2.2.0.0                         Jul 97
 271
 272         * added section 4.1 `Architecture specification strings':
 273           use
 274                &lt;arch&gt;-linux
 275           where &lt;arch&gt; is one of the following:
 276                i386, alpha, arm, m68k, powerpc, sparc.
 277
 278         * detailed rules for /usr/local
 279
 280         * user ID's
 281
 282         * editor/pager policy
 283
 284         * cron jobs
 285
 286         * device files
 287
 288         * don't install shared libraries as executable
 289
 290         * app-defaults files may not be conffiles
 291
 292 2.1.3.2, 2.1.3.1, 2.1.3.0       Mar 97
 293
 294         * two programs with different functionality must not have the
 295           same name
 296
 297         * "Webstandard 3.0"
 298
 299         * "Standard for Console Messages"
 300
 301         * Libraries should be compiled with `-D_REENTRANT'
 302
 303         * Libraries should be stripped with "strip --strip-unneeded"
 304
 305 2.1.2.2, 2.1.2.1, 2.1.2.0       Nov 96
 306
 307         * Some changes WRT shared libraries
 308
 309 2.1.1.0                         Sep 96
 310
 311         * No hard links in source packages
 312
 313         * Do not use dpkg-divert or update-alternatives without consultation
 314
 315         * Shared libraries must be installed stripped
 316
 317 2.1.0.0                         Aug 96
 318
 319         * Upstream changelog must be installed too
 320 </pre>
 321
 322     <hr>
 323
 324   </body>
 325 </html>
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336 <!-- Keep this comment at the end of the file
 337 Local variables:
 338 mode: sgml
 339 sgml-indent-data: t
 340 sgml-live-element-indicator: t
 341 sgml-set-face: t
 342 End:
 343 -->