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