<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
- <!-- -*- Mode: Sgml -*-
+ <!-- -*- Mode: Sgml -*-
upgrading-checklist.html
- Author : Manoj Srivastava ( srivasta@tiamat.datasync.com )
+ Author : Manoj Srivastava ( srivasta@tiamat.datasync.com )
Created On : Thu Oct 29 20:54:48 1998
Created On Node : tiamat.datasync.com
Last Modified By : Manoj Srivastava
- Last Modified On : Thu Oct 29 22:12:16 1998
- Last Machine Used: tiamat.datasync.com
- Update Count : 6
+ Last Modified On : Sat Jun 18 00:16:40 2005
+ Last Machine Used: glaurung.internal.golden-gryphon.com
+ Update Count : 51
Status : Unknown, Use with caution!
- HISTORY :
- Description :
+ HISTORY :
+ Description :
-->
<p>
The checklist below has been created to simplify the upgrading process
-of old packages. Note, that this list is not `official.' If you have
+of old packages. Note that this list is not `official'; it simply
+gives an indication of what has changed and whether you are likely to
+need to make changes to your package in light of this. If you have
doubts about a certain topic, if you need more details, or if you
think some other package does not comply with policy, please refer to
-the Policy Manual.
+the Policy Manual itself. All of the changes from version 3.0.0
+onwards indicate which section of the Policy Manual discusses the
+issue: [3.4] means section 3.4. The section numbering changed when
+the packaging manual was incorporated into policy; the section numbers
+used below refer to the current version.
</p>
<p>
-Here is how the check list works: Check out which policy version your
-packages complies with currently. Than move upwards until the top and
-check which of the items on the list might concern your package. If an
-item does not give you enough details, please check out the Policy
-Manual.
+Here is how the check list works: Check which policy version your
+package complies with currently (indicated in the "Standards-Version"
+field of the source package). Then move upwards until the top and
+check which of the items on the list might concern your package. Note
+which sections of policy discuss this, and then check out the Policy
+Manual for details. If you are upgrading from Policy version < 2.5.0,
+it may be easier to check through the whole of policy instead of
+picking your way through this list.
</p>
<h2>The checklist</h2>
<pre>
-
-2.5.0.0 Oct 98
+3.7.4.0 unreleased
+
+ * The base section has been removed. contrib and non-free have been
+ removed from the section list; they are only categories. The base
+ system is now defined by priority. [2.4, 3.7]
+ * If dpkg-source -x doesn't provide the source that will be compiled,
+ a debian/rules patch target is recommended and should do whatever
+ else is necessary. [4.9]
+ * Standardized the format of DEB_BUILD_OPTIONS. Specified permitted
+ characters for tags, required that tags be whitespace-separated,
+ allowed packages to assume non-conflicting tags, and required
+ unknown flags be ignored. [4.9.1, 10.1]
+ * Added parallel=n to the standardized DEB_BUILD_OPTIONS tags,
+ indicating that a package should be built using up to n parallel
+ processes if the package supports it [4.9.1]
+ * Debian packages should not use convience copies of code from other
+ packages unless the included package is explicitly intended to be
+ used that way. [4.13]
+ * If dpkg-source -x doesn't produce source ready for editing and
+ building with dpkg-buildpackage, packages should include a
+ debian/README.source file explaining how to generate the patched
+ source, add a new modification, and remove an existing
+ modification. This file may also be used to document packaging a
+ new upstream release and any other complexity of the Debian build
+ process. [4.14]
+ * The Uploaders field in debian/control may be wrapped. [5.6.3]
+ * New Homepage field for upstream web sites. [5.6.23]
+ * The Breaks field declares that this package breaks another and
+ prevents installation of the breaking package unless the package
+ named in Breaks is deconfigured first. This field should not be
+ used until the dpkg in Debian stable supports it. [6.5, 6.6, 7]
+ * Files in /etc/cron.{hourly,daily,weekly,monthly} must be
+ configuration files (upgraded from should). Mention the hourly
+ directory. [9.5]
+ * Manual pages in locale-specific directories should use either the
+ legacy encoding for that directory or UTF-8. Country names should
+ not be included in locale-specific manual page directories unless
+ indicating a significant difference in the language. All
+ characters in the manual page source should be representable in the
+ legacy encoding for a locale even if the man page is encoded in
+ UTF-8. [12.1]
+ * The Apache 2.0 license is now in common-licenses and should be
+ referenced rather than quoted in debian/copyright. [12.5]
+ * Packages in contrib and non-free should state in the copyright file
+ that the package is not part of Debian GNU/Linux and briefly
+ explain why. [12.5]
+
+3.7.3.0 Dec 2007
+
+ * Package version numbers may contain tildes, which sort before
+ anything, even the end of a part. [5.6.12]
+ * Scripts may assume that /bin/sh supports local (at a basic level)
+ and that its test builtin (if any) supports -a and -o binary
+ logical operators. [10.4]
+ * The substitution variable ${binary:Version} should be used in place
+ of ${Source-Version} for dependencies between packages of the same
+ library. [8.5]
+ * Substantial reorganization and renaming of sections in the Debian
+ menu structure. Packages with menu entries should be reviewed to
+ see if the menu section has been renamed or if one of the new
+ sections would be more appropriate. [menu policy]
+ * The Source field in a .changes file may contain a version number
+ in parentheses. [5.6.1]
+ * The acceptable values for the Urgency field are low, medium, high,
+ critical, or emergency. [5.6.17]
+ * The shlibs file now allows an optional type field, indicating the
+ type of package for which the line is valid. The only currently
+ supported type is udeb, used with packages for the Debian
+ Installer. [8.6]
+ * Packages following the Debian Configuration management
+ specification must allow for translation of their messages by using
+ a gettext-based system such as po-debconf. [3.9.1]
+ * GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should
+ be referenced rather than quoted in debian/copyright. [12.5]
+
+3.7.2.2 Oct 2006
+
+ * Maintainer scripts must not be world writeable (up from a
+ should to a must) [6.1]
+
+3.7.2.0 Apr 2006
+
+ * Revert the cgi-lib change. [11.5]
+
+3.7.1.0 Apr 2006
+
+ * It is now possible to create shared libraries without
+ relocatable code (using -fPIC) in certain exceptional cases,
+ provided some procedures are followed, and for creating static
+ libraries with relocatable code (again, using -fPIC).
+ Discussion on debian-devel@lists.debian.org, getting a rough
+ consensus, and documenting it in README.Debian constitute most
+ of the process. [10.2]
+ * Packages should install any relevant files into the directories
+ /usr/include/X11/and /usr/lib/X11/, but if they do so, they
+ must pre-depend on x11-common (>= 1:7.0.0) [11.8.7]
+
+3.7.0.0 Apr 2006
+
+ * Packages shipping web server CGI files are expected to install
+ them in /usr/lib/cgi-lib/ directories. This location change
+ perhaps should be documented in NEWS [11.5]
+ * Web server packages should include a standard scriptAlias of
+ cgi-lib to /usr/lib/cgi-lib. [11.5]
+ * The version of FHS mandated by policy has been upped to
+ 2.3. There should be no changes required for most packages,
+ though new top level directories /media, /srv, etc may be of
+ interest. [9.1.1]
+ * All fields, apart from the Uploaders field, in the control file
+ are supposed to be a single logical line, which may be spread
+ over multiple physical lines (newline followed by space is
+ elided). However, any parser for the control file must allow
+ the Uploaders field to be spread over multiple physical lines
+ as well, to prepare for future changes. [ 5.1, 5.6.3 ]
+ * When scripts are installed into a directory in the system
+ PATH, the script name should not include an extension that
+ denotes the scripting language currently used to implement it.
+ [ 10.4 ]
+ * packages that invoke initscripts now must use invoke-rc.d to do
+ so since it also pays attention to run levels and other local
+ constraints. [ 9.3.3.2 ]
+ * We no longer use /usr/X11R6, since we have migrated away to
+ using Xorg paths. This means, for one thing, fonts live in
+ /usr/share/fonts/X11/ now, and /usr/X11R6 is gone.
+ [ 11.8.5.2, 11.8.7, etc]
+
+3.6.2.0 2005
+
+ * Recommend doc-base, and not menu, for registering package documentation.
+ * Run time support programs should live in subdirectories of
+ /usr/lib/ or /usr/share, and preferably the shared lib is named
+ the same as the package name (to avoid name collisions). [8.1]
+ * It is recommended that HTTP servers provide an alias /images to
+ allow packages to share image files with the web server [11.5]
+
+3.6.1.0 Aug 2003
+
+ + Prompting the user should be done using debconf. Non debconf
+ user prompts are now deprecated. [3.10.1]
+
+3.6.0 Jul 2003
+
+ - Restructuring causing shifts in section numbers and bumping of
+ the minor version number:
+ + Many packaging manual appendices that were integrated into policy
+ sections are now empty, and replaced with links to the Policy.
+ In particular, the appendices that included the list of control
+ fields were updated (new fields like Closes, Changed-By were added)
+ and the list of fields for each of control, .changes and .dsc files
+ is now in Policy, and they're marked mandatory, recommended or
+ optional based on the current practice and the behavior of the
+ deb-building tool-chain.
+ + Elimination of needlessly deep section levels, primarily in the
+ chapter Debian Archive, from which two new chapters were split out,
+ Binary packages and Source packages. What remained was reordered
+ properly, that is, some sect1s became sects etc.
+ + Several sections that were redundant, crufty or simply not designed
+ with any sort of vision, were rearranged according to the formula that
+ everything should be either in the same place or properly interlinked.
+ Some things remained split up between different chapters when they
+ talked about different aspects of files: their content, their syntax,
+ and their placement in the file system. In particular, see the new
+ sections about changelog files.
+ - Added Games/Simulation and Apps/Education to menu sub-policy
+ [menu policy]
+ - Debian changelogs should be UTF-8 encoded. [C.2.2]
+ - shared libraries must be linked against all libraries that they
+ use symbols from in the same way that binaries are. [10.2]
+ - build-depends-indep need not be satisfied during clean
+ target. [7.6]
+
+3.5.10 May 2003
+
+ - packages providing the x-terminal-emulator virtual package
+ ought to ensure that they interpret the command line exactly
+ like xterm does. [11.8.3]
+ - Window managers compliant with the Window Manager Specification
+ Project may add 40 points for ranking in the alternatives [11.8.4]
+
+3.5.9.0 Mar 2003
+
+ - The section describing the Description: package field once again has
+ full details of the long description format. [3.4.2]
+ - Clarified that if a package has non-build-essential
+ build-dependencies, it should have them listed in the Build-Depends
+ and related fields (i.e. it's not merely optional). [4.2]
+ - When asked to restart a service that isn't already running,
+ the init script should start the service. [9.3.2]
+ - If the purpose of a package is to provide examples, then the
+ example files can be installed into <tt>/usr/share/doc/package</tt>
+ (rather than <tt>/usr/share/doc/package/examples</tt>). [12.6]
+
+3.5.8.0 Nov 2002
+
+ - It is no longer necessary to keep a log of changes to the upstream
+ sources in the copyright file. Instead, all such changes should be
+ documented in the changelog file. [12.7]
+ - <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
+ <tt>Build-Depends-Indep</tt>, and
+ <tt>Build-Conflicts-Indep</tt> must also be satisfied when the
+ clean target is called. [7.6]
+ - A new Apps/Science menu section is available [menu policy]
+ - debconf specification cleared up, various changes. [debconf
+ policy]
+ - It is no longer recommended to create symlinks from nonexistent
+ manual pages to undocumented(7). Missing manual pages for programs
+ are still a bug. [12.1]
+
+3.5.7.0 Aug 2002
+
+ - Packages no longer have to ask permission to call MAKEDEV in
+ postinst, merely notifying the user ought to be enough. [10.6]
+ - cryptographic software may now be included in the main
+ archive. [2.2.4]
+ - task packages are no longer permitted; tasks are now created by a
+ special Tasks: field in the control file. [3.9]
+ - window managers that support netwm can now add 20 points when
+ they add themselves as an alternative for
+ /usr/bin/x-window-manager [11.8.4]
+ - The default compilation options have now changed, one should
+ provide debugging symbols in all cases, and optionally step
+ back optimization to -O0, depending on the DEB_BUILD_OPTIONS
+ environment variable. [10.1]
+ - Added mention of build-arch, build-indep, etc, in describing
+ the relationships with `Build-Depends', `Build-Conflicts',
+ `Build-Depends-Indep', and `Build-Conflicts-Indep'. May need to
+ review the new rules. [7.6, 4.8]
+ - Changed rules on how, and when, to invoke ldconfig in maintainer
+ scripts. Long rationale. [8]
+ - [Added the last note in 3.5.6 upgrading checklist item regarding
+ build rules, please see below]
+
+3.5.6.0 Jul 2001
+
+ - Emacs and TeX are no longer mandated by policy to be priority
+ standard packages [2.5]
+ - Programs that access docs need to do so via /usr/share/doc, and
+ not via /usr/doc/ as was the policy previously [11.5]
+ - Putting documentation in /usr/doc versus /usr/share/doc is now
+ a ``serious'' policy violation. [12.3]
+ - For web servers, one should not provide non-local access to the
+ /usr/share/doc hierarchy. If one can't provide access controls for
+ the http://localhost/doc/ directory, then it is preferred that one
+ ask permission to expose that information during the install. [11.5]
+ - There are new rules for build-indep/build-arch targets and
+ there is a new Build-Depend-Indep semantic. [7]
+
+3.5.5.0 May 2001
+
+ - Manpages should not rely on header information to have
+ alternative manpage names available; it should only use
+ symlinks or .so pages to do this [12.1]
+ - [Clarified note in 3.5.3.0 upgrading checklist regarding
+ examples and templates: this refers only to those examples used
+ by scripts; see section 10.7.3 for the whole story]
+ - Included a new section 10.9.1 describing the use of
+ dpkg-statoverride; this does not have the weight of policy
+ - Clarify Standards-Version: you don't need to rebuild your
+ packages just to change the Standards-Version!
+ - Plugins are no longer bound by all the rules of shared
+ libraries [10.2]
+ - X Windows related things:
+ * Clarification of priority levels of X Window System related
+ packages [11.8.1]
+ * Rules for defining x-terminal-emulator improved [11.8.3]
+ * X Font policy rewritten: you must read this if you provide
+ fonts for the X Window System [11.8.5]
+ * Packages must not ship /usr/X11R6/lib/X11/app-defaults/ [11.8.6]
+ * X-related packages should usually use the regular FHS
+ locations; imake-using packages are exempted from this [11.8.7]
+ * OpenMotif linked binaries have the same rules as
+ OSF/Motif-linked ones [11.8.8]
+
+3.5.4.0 Apr 2001
+
+ - The system-wide mail directory is now /var/mail, no longer
+ /var/spool/mail. Any packages accessing the mail spool should
+ access it via /var/mail and include a suitable Depends field;
+ details in [11.6]
+ - The perl policy is now part of Debian policy proper. Perl
+ programs and modules should follow the current Perl policy
+ [11.9; perl-policy]
+
+3.5.3.0 Apr 2001
+
+ - Build-Depends arch syntax has been changed to be less
+ ambiguous. This should not affect any current packages [7.1]
+ - Examples and templates files for use by scripts should now live
+ in /usr/share/<package> or /usr/lib/<package>, with
+ symbolic links from /usr/share/doc/<package>/examples as
+ needed [10.7.3]
+
+3.5.2.0 Feb 2001
+
+ - X app-defaults directory has moved from
+ /usr/X11R6/lib/X11/app-defaults to /etc/X11/app-defaults [11.8.6]
+
+3.5.1.0 Feb 2001
+
+ - dpkg-shlibdeps now uses objdump, so shared libraries have to be
+ run through dpkg-shlibdeps as well as executables [8.1]
+
+3.5.0.0 Jan 2001
+
+ - Font packages for the X Window System must now declare a
+ dependency on xutils (>= 4.0.2) [11.8.5]
+
+3.2.1.1 Jan 2001
+
+ - Daemon startup scripts in /etc/init.d/ should not contain
+ modifiable parameters; these should be moved to a file in
+ /etc/default/; see [9.3.2] for details
+ - Files in /usr/share/doc must not be referenced by any
+ program. If such files are needed, they must be placed in
+ /usr/share/<package>/, and symbolic links created as required
+ in /usr/share/doc/<package>/ [12.3]
+ - Much of the packaging manual has now been imported into the
+ policy document
+
+3.2.1.0 Aug 00
+
+ - A package of priority standard or higher may provide two
+ binaries, one compiled with support for the X Window System,
+ and the other without [11.8.1]
+
+3.2.0.0 Aug 00
+
+ - By default executables should not be built with the debugging
+ option -g. Instead, it is recommended to support building the
+ package with debugging information optionally. Details in [10.1]
+ - Policy for packages where the upstream uses HTML changelog
+ files has been expanded. In short, a plain text changelog file
+ should always be generated for the upstream changes [12.8]
+ - Please note that the new release of the X window system (3.2)
+ shall probably need sweeping changes in policy
+ - Policy for packages providing the following X-based features
+ has been codified:
+ - X server (virtual package xserver) [11.8.2]
+ - X terminal emulator (virtual package x-terminal-emulator) [11.8.3]
+ - X window manager (virtual package x-window-manager, and
+ /usr/bin/x-window-manager alternative, with priority
+ calculation guidelines) [11.8.4]
+ - X fonts (this section has been written from scratch) [12.8.5]
+ - X application defaults [11.8.6]
+ - Policy for packages using the X Window System and FHS issues
+ has been clarified; see [11.8.7]
+ - No package may contain or make hard links to conffiles [11.7.3]
+ - Noted that newer dpkg versions do not require extreme care in
+ always creating the shared lib before the symlink, so the unpack
+ order be correct [8]
+
+3.1.1.0 Nov 1999
+
+ - Correction to semantics of architecture lists in Build-Depends
+ etc. Should not affect many packages [7.1]
+
+3.1.0.0 Oct 1999
+
+ - /usr/doc/<package> has to be a symlink pointing to
+ /usr/share/doc/<package>, to be maintained by postinst
+ and prerm scripts. Details are in [defunct]
+ - Introduced source dependencies (Build-Depends, etc.) [7.1, 7.6]
+ - /etc/rc.boot has been deprecated in favour of /etc/rcS.d.
+ (Packages should not be touching this directory, but should use
+ update-rc.d instead) [9.3.4]
+ - update-rc.d is now the *only* allowable way of accessing the
+ /etc/rc?.d/[SK]??* links. Any scripts which manipulate them
+ directly must be changed to use update-rc.d instead. (This is
+ because the file-rc package handles this information in an
+ incompatible way.) [9.3.3]
+ - Architecture-specific examples go in /usr/lib/<package>/examples
+ with symlinks from /usr/share/doc/<package>/examples/* or from
+ /usr/share/doc/<package>/examples itself [12.7]
+ - Updated FHS to a 2.1 draft; this reverts /var/state to
+ /var/lib [9.1.1]
+ - Added MIME sub-policy document [9.7; mime-policy]
+ - VISUAL is allowed as a (higher priority) alternative to EDITOR [12.4]
+ - Modified liblockfile description, which affects
+ mailbox-accessing programs. Please see the policy document for
+ details [11.6]
+ - If a package provides a changelog in HTML format, a text-only
+ version should also be included. (Such a version may be prepared
+ using lynx -dump -nolist.) [12.7]
+ - Description of how to handle version numbers based on dates
+ added [3.2.1]
+
+3.0.1.0 Jul 1999
+
+ - Added the clarification that the .la files are essential for the
+ packages using libtool's libltdl library, in which case the
+ .la files must go in the run-time library package [10.2]
+
+3.0.0.0 Jun 1999
+
+ - Debian formally moves from the FSSTND to the FHS. This is a
+ major change, and the implications of this move are probably
+ not all known. [9.1]
+ - Only 3 digits of the Standards version need be included in
+ control files, though all four digits are still permitted. [4.1]
+ - The location of the GPL has changed to
+ /usr/share/common-licenses. This may require changing the
+ copyright files to point to the correct location of the GPL and
+ other major licenses [12.6]
+ - Packages that use libtool to create shared libraries must
+ include the .la files in the -dev packages [10.2]
+ - Use logrotate to rotate log files [10.8]
+ - section 5.8 has been rewritten (Programs for the X Window
+ System) [now 11.8]
+ - There is now an associated menu policy, in a separate document,
+ that carries the full weight of Debian policy [9.6; menu-policy]
+ - Programs which need to modify the files /var/run/utmp,
+ /var/log/wtmp and /var/log/lastlog must be installed setgid utmp [11.3]
+
+
+** Please note that section numbers below this point may not be up to date **
+
+
+2.5.0.0 Oct 1998
Policy Manual:
- Rearranged the manual to create a new Section 4, Files
"Configuration files", moving the Section 4.8 ("Permissions
and owners") to Section 4.9. All subsections of the old
Section 5 after 5.5 were moved down to fill in the number
- gap.
- - Modified the section about changelog files to accomodate
+ gap.
+ - Modified the section about changelog files to accommodate
upstream changelogs which were formatted as HTML/ These
- upstream chagelog files should now be accessible as
- /usr/doc/package/changelog.html.gz
+ upstream changelog files should now be accessible as
+ /usr/doc/package/changelog.html.gz
+ Symlinks are permissible to link the real, or upstream,
changelog name to the Debian mandated name.
- Clarified that HTML documentation should be present in some
- Corrected all references to the location of the copyright
files. The correct location is /usr/doc/package/copyright
- Ratified the architecture specification strings to cater to the
- HURD.
+ HURD.
-2.4.1.0 Apr 98
+2.4.1.0 Apr 1998
Policy Manual:
- Updated section 3.3.5 Symbolic links:
ldconfig must be called in the postinst script if the package
installs shared libraries
(cf., Policy Weekly Issue #6, fixes:bug#20515)
-
-2.4.0.0 Jan 98
+
+2.4.0.0 Jan 1998
- Updated section 3.3.4 Scripts:
+ /bin/sh may be any POSIX compatible shell
+ /etc/news/organization and /etc/news/server should be supported
by all news servers and clients
- - Updated section 4.7 Programs for the X Windows system:
+ - Updated section 4.7 Programs for the X Window System:
+ programs requiring a non-free Motif library should be provided
as foo-smotif and foo-dmotif package
+ if lesstif works reliably for such program, it should be linked
+ games for X Windows have to be installed in /usr/games, just as
non-X games
-2.3.0.1, 2.3.0.0 Sep 97
+2.3.0.1, 2.3.0.0 Sep 1997
* new section `4.2 Daemons' including rules for
/etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
* updated section about `Configuration files':
- packages may not touch other packages' configuration files
+ packages may not touch other packages' configuration files
* MUAs and MTAs have to use liblockfile
-2.2.0.0 Jul 97
+2.2.0.0 Jul 1997
* added section 4.1 `Architecture specification strings':
use
- <arch>-linux
+ <arch>-linux
where <arch> is one of the following:
i386, alpha, arm, m68k, powerpc, sparc.
* app-defaults files may not be conffiles
-2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 97
+2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 1997
* two programs with different functionality must not have the
same name
* Libraries should be stripped with "strip --strip-unneeded"
-2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 96
+2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 1996
* Some changes WRT shared libraries
-2.1.1.0 Sep 96
+2.1.1.0 Sep 1996
* No hard links in source packages
-
+
* Do not use dpkg-divert or update-alternatives without consultation
* Shared libraries must be installed stripped
-2.1.0.0 Aug 96
+2.1.0.0 Aug 1996
* Upstream changelog must be installed too
</pre>
</body>
</html>
-
-
-
-
-
-
-
-
-
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
projects / debian / debian-policy.git / blobdiff