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 : Fri Jan 19 14:01:36 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 - 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/<package> or /usr/lib/<package>, with
53 symbolic links from /usr/share/doc//<package>/examples as
58 - X app-defaults directory has moved from
59 /usr/X11R6/lib/X11/app-defaults to /etc/X11/app-defaults.
63 - dpkg-shlibdeps now uses objdump, so shared libraries have to be
64 run through dpkg-shlibdeps as well as executables
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
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
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.
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
124 - No package may contain or make hard links to conffiles.
127 - Noted that newer dpkg versions do not require extreme care in
128 always creating the shared lib before the symlink, so the unpack
134 - Correction to semantics of architecture lists in Build-Depends
135 etc. Should not affect many packages.
140 - /usr/doc/<package> has to be a symlink pointing to
141 /usr/share/doc/<package>. 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
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
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
158 - Compiled examples go in /usr/lib/<package>/examples with
159 symlinks from /usr/share/doc/<package>/examples/* or from
160 /usr/share/doc/<package>/examples itself.
161 - Updated FHS to a 2.1 draft; this reverts /var/state to
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
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.)
173 - Description of how to handle version numbers based on dates
174 added: see section 5.1.
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.
188 - Debian formally moves from the FSSTND to the FHS. This is a
189 major change, and the implications of this move are probably
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
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
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
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
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
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)
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)
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)
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
260 + scripts which create files in world-writable directories
261 (e.g., in /tmp) should use tempfile or mktemp for creating
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
268 - Updated section 3.3.6 Device files:
269 + /dev/tty* serial devices should be used instead of /dev/cu*
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
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
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
287 - New section 3.8 Keyboard configuration:
288 + details about how the backspace and delete keys should be
291 - New section 3.9 Environment variables:
292 + no program must depend on environment variables to get a
293 reasonable default configuration
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
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
305 - Updated section 4.9 Games:
306 + games for X Windows have to be installed in /usr/games, just as
309 2.3.0.1, 2.3.0.0 Sep 97
311 * new section `4.2 Daemons' including rules for
312 /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
314 * updated section about `Configuration files':
315 packages may not touch other packages' configuration files
317 * MUAs and MTAs have to use liblockfile
321 * added section 4.1 `Architecture specification strings':
324 where <arch> is one of the following:
325 i386, alpha, arm, m68k, powerpc, sparc.
327 * detailed rules for /usr/local
331 * editor/pager policy
337 * don't install shared libraries as executable
339 * app-defaults files may not be conffiles
341 2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 97
343 * two programs with different functionality must not have the
348 * "Standard for Console Messages"
350 * Libraries should be compiled with `-D_REENTRANT'
352 * Libraries should be stripped with "strip --strip-unneeded"
354 2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 96
356 * Some changes WRT shared libraries
360 * No hard links in source packages
362 * Do not use dpkg-divert or update-alternatives without consultation
364 * Shared libraries must be installed stripped
368 * Upstream changelog must be installed too
376 <!-- Keep this comment at the end of the file
380 sgml-live-element-indicator: t