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 : Wed Jun 30 12:35:32 1999
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>
50 - Correction to semantics of architecture lists in Build-Depends
51 etc. Should not affect many packages.
56 - /usr/doc/<package> has to be a symlink pointing to
57 /usr/share/doc/<package>. This symlink has to be
58 maintained by postinst and prerm, because dpkg will cause
59 problems otherwise. Create/remote the symlinks using debhelper
60 or see section "6.4. Accessing the documentation" for more
62 - Introduced source dependencies. (Whereas this ought to demand a
63 major policy number rise, we've only just had one of them, so
64 I'm going to use a minor number instead.)
65 - /etc/rc.boot has been deprecated in favour of /etc/rcS.d.
66 Packages should not be touching this directory, anyway, but
67 should use update-rc.d instead.
68 - update-rc.d is now the *only* allowable way of accessing the
69 /etc/rc?.d/[SK]??* links. Any scripts which manipulate them
70 directly must be changed to use update-rc.d instead. (This is
71 because the file-rc package handles this information in an
73 - Compiled examples go in /usr/lib/<package>/examples with
74 symlinks from /usr/share/doc/<package>/examples/* or from
75 /usr/share/doc/<package>/examples itself.
76 - Updated FHS to a 2.1 draft; this reverts /var/state to
78 - Added MIME sub-policy document.
79 - VISUAL is allowed as a (higher priority) alternative to EDITOR.
80 - Modified liblockfile description, which affects
81 mailbox-accessing programs. Please see the policy document for
83 - If a package provides a changelog in HTML format, a text-only
84 version should also be included. Such a version may be prepared
85 using lynx -dump -nolist.)
88 - Description of how to handle version numbers based on dates
89 added: see section 5.1.
95 - Added the clarification that the .la files are essential for the
96 packages using libtool's libltdl library, in which case the
97 .la files must go in the run-time library package.
103 - Debian formally moves from the FSSTND to the FHS. This is a
104 major change, and the implications of this move are probably
106 - Only 3 digits of the Standards version need be included in
107 control files, though all four digits are still permitted.
108 - The location of the GPL has changed to
109 /usr/share/common-licenses. This may require changing the
110 copyright files to point to the correct location of the GPL and
112 - Packages that use libtool to create shared libraries must
113 include the .la files in the -dev packages.
114 - Use logrotate to rotate log files
115 - section 5.8 has been rewritten (Programs for the X Window
117 - There is now anassi=ociated menu policy, in a separate document,
118 that carries the full weight of Debian policy.
119 - The files `/var/run/utmp', `/var/log/wtmp' and
120 `/var/log/lastlog' must be installed writeable by group
121 utmp. Programs who need to modify those files must be installed
128 - Rearranged the manual to create a new Section 4, Files
129 + Section 3.3 ("Files") was moved to Section 4. The Sections
130 that were Section 4 and Section 5 were moved down to become
131 Section 5 and Section 6.
132 + What was Section 5.5 ("Log files") is now a subsection of the
133 new Section 4 ("Files"), becoming section 4.8, placed after
134 "Configuration files", moving the Section 4.8 ("Permissions
135 and owners") to Section 4.9. All subsections of the old
136 Section 5 after 5.5 were moved down to fill in the number
138 - Modified the section about changelog files to accomodate
139 upstream changelogs which were formatted as HTML/ These
140 upstream chagelog files should now be accessible as
141 /usr/doc/package/changelog.html.gz
142 + Symlinks are permissible to link the real, or upstream,
143 changelog name to the Debian mandated name.
144 - Clarified that HTML documentation should be present in some
145 package, though not necessarily the main binary package.
146 - Corrected all references to the location of the copyright
147 files. The correct location is /usr/doc/package/copyright
148 - Ratified the architecture specification strings to cater to the
154 - Updated section 3.3.5 Symbolic links:
155 + symbolic links within a toplevel directory should be relative,
156 symbolic links between toplevel directories should be absolute
157 (cf., Policy Weekly Issue#6, topic 2)
159 - Updated section 4.9 Games:
160 + manpages for games should be installed in /usr/man/man6
161 (cf., Policy Weekly Issue#6, topic 3)
164 - Updated prefix of chapter 12, Shared Libraries:
165 ldconfig must be called in the postinst script if the package
166 installs shared libraries
167 (cf., Policy Weekly Issue #6, fixes:bug#20515)
171 - Updated section 3.3.4 Scripts:
172 + /bin/sh may be any POSIX compatible shell
173 + scripts including bashisms have to specify /bin/bash as
175 + scripts which create files in world-writable directories
176 (e.g., in /tmp) should use tempfile or mktemp for creating
179 - Updated section 3.3.5 Symbolic Links:
180 + symbolic links referencing compressed files must have the same
181 file extension as the referenced file
183 - Updated section 3.3.6 Device files:
184 + /dev/tty* serial devices should be used instead of /dev/cu*
186 - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
187 + all /etc/init.d scripts have to provide the following options:
188 start, stop, restart, force-reload
189 + the reload option is optional and must never stop and restart
192 - Updated section 3.5 Cron jobs:
193 + cron jobs that need to be executed more often than daily should
194 be installed into /etc/cron.d
196 - Updated section 3.7 Menus:
197 + removed section about how to register HTML docs to `menu'
198 (the corresponding section in 4.4, Web servers and applications,
199 has been removed in policy 2.2.0.0 already, so this one was
202 - New section 3.8 Keyboard configuration:
203 + details about how the backspace and delete keys should be
206 - New section 3.9 Environment variables:
207 + no program must depend on environment variables to get a
208 reasonable default configuration
210 - New section 4.6 News system configuration:
211 + /etc/news/organization and /etc/news/server should be supported
212 by all news servers and clients
214 - Updated section 4.7 Programs for the X Windows system:
215 + programs requiring a non-free Motif library should be provided
216 as foo-smotif and foo-dmotif package
217 + if lesstif works reliably for such program, it should be linked
218 against lesstif and not against a non-free Motif library
220 - Updated section 4.9 Games:
221 + games for X Windows have to be installed in /usr/games, just as
224 2.3.0.1, 2.3.0.0 Sep 97
226 * new section `4.2 Daemons' including rules for
227 /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
229 * updated section about `Configuration files':
230 packages may not touch other packages' configuration files
232 * MUAs and MTAs have to use liblockfile
236 * added section 4.1 `Architecture specification strings':
239 where <arch> is one of the following:
240 i386, alpha, arm, m68k, powerpc, sparc.
242 * detailed rules for /usr/local
246 * editor/pager policy
252 * don't install shared libraries as executable
254 * app-defaults files may not be conffiles
256 2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 97
258 * two programs with different functionality must not have the
263 * "Standard for Console Messages"
265 * Libraries should be compiled with `-D_REENTRANT'
267 * Libraries should be stripped with "strip --strip-unneeded"
269 2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 96
271 * Some changes WRT shared libraries
275 * No hard links in source packages
277 * Do not use dpkg-divert or update-alternatives without consultation
279 * Shared libraries must be installed stripped
283 * Upstream changelog must be installed too
300 <!-- Keep this comment at the end of the file
304 sgml-live-element-indicator: t