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