1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
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
13 Status : Unknown, Use with caution!
20 <title>Policy checklist for upgrading your packages</title>
24 <h1>Policy checklist for upgrading your packages</h1>
26 <h2>About the checklist</h2>
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
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
44 <h2>The checklist</h2>
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> (>= 2.1.3-13), or on
56 <em>base-files</em> (>= 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.
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/<package> or /usr/lib/<package>, with
67 symbolic links from /usr/share/doc//<package>/examples as
72 - X app-defaults directory has moved from
73 /usr/X11R6/lib/X11/app-defaults to /etc/X11/app-defaults.
77 - dpkg-shlibdeps now uses objdump, so shared libraries have to be
78 run through dpkg-shlibdeps as well as executables
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
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
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.
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
138 - No package may contain or make hard links to conffiles.
141 - Noted that newer dpkg versions do not require extreme care in
142 always creating the shared lib before the symlink, so the unpack
148 - Correction to semantics of architecture lists in Build-Depends
149 etc. Should not affect many packages.
154 - /usr/doc/<package> has to be a symlink pointing to
155 /usr/share/doc/<package>. 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
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
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
172 - Compiled examples go in /usr/lib/<package>/examples with
173 symlinks from /usr/share/doc/<package>/examples/* or from
174 /usr/share/doc/<package>/examples itself.
175 - Updated FHS to a 2.1 draft; this reverts /var/state to
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
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.)
187 - Description of how to handle version numbers based on dates
188 added: see section 5.1.
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.
202 - Debian formally moves from the FSSTND to the FHS. This is a
203 major change, and the implications of this move are probably
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
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
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
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
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
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)
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)
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)
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
274 + scripts which create files in world-writable directories
275 (e.g., in /tmp) should use tempfile or mktemp for creating
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
282 - Updated section 3.3.6 Device files:
283 + /dev/tty* serial devices should be used instead of /dev/cu*
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
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
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
301 - New section 3.8 Keyboard configuration:
302 + details about how the backspace and delete keys should be
305 - New section 3.9 Environment variables:
306 + no program must depend on environment variables to get a
307 reasonable default configuration
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
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
319 - Updated section 4.9 Games:
320 + games for X Windows have to be installed in /usr/games, just as
323 2.3.0.1, 2.3.0.0 Sep 97
325 * new section `4.2 Daemons' including rules for
326 /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
328 * updated section about `Configuration files':
329 packages may not touch other packages' configuration files
331 * MUAs and MTAs have to use liblockfile
335 * added section 4.1 `Architecture specification strings':
338 where <arch> is one of the following:
339 i386, alpha, arm, m68k, powerpc, sparc.
341 * detailed rules for /usr/local
345 * editor/pager policy
351 * don't install shared libraries as executable
353 * app-defaults files may not be conffiles
355 2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 97
357 * two programs with different functionality must not have the
362 * "Standard for Console Messages"
364 * Libraries should be compiled with `-D_REENTRANT'
366 * Libraries should be stripped with "strip --strip-unneeded"
368 2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 96
370 * Some changes WRT shared libraries
374 * No hard links in source packages
376 * Do not use dpkg-divert or update-alternatives without consultation
378 * Shared libraries must be installed stripped
382 * Upstream changelog must be installed too
390 <!-- Keep this comment at the end of the file
394 sgml-live-element-indicator: t