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