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