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