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