7 The checklist below has been created to simplify the upgrading process
8 of old packages. This list is not official or normative. It only
9 provides an indication of what has changed and whether you are likely to
10 need to make changes to your package in light of this. If you have
11 doubts about a certain topic, if you need more details, or if you think
12 some other package does not comply with policy, please refer to the
15 All of the changes from version 3.0.0 onwards indicate which section of
16 the Policy Manual discusses the issue. The section numbering should
17 still be accurate for changes back to the 2.5.0 release. Before that
18 point, the sections listed here probably no longer correspond to
19 sections in the modern Policy Manual.
21 Here is how the check list works: Check which policy version your
22 package was checked against last (indicated in the ``Standards-Version``
23 field of the source package). Then move upwards until the top and check
24 which of the items on the list might concern your package. Note which
25 sections of policy discuss this, and then check out the Policy Manual
26 for details. Once you've made all necessary changes to match the current
27 rules, update the value of ``Standards-Version`` to the current Policy
30 If an item in the list is followed by the name of a Lintian tag in
31 square brackets, it indicates that the policy requirement is covered
32 by that Lintian tag. The lack of such an annotation does not mean
33 that no Lintian tag exists to cover the requirement. Our coverage of
34 these annotations is quite incomplete, and patches to this checklist
37 The sections in this checklist match the values for the
38 ``Standards-Version`` control field in omitting the minor patch version,
39 except in the two anomalous historical cases where normative
40 requirements were changed in a minor patch release.
48 debian/changelog must exist in source packages.
53 Released August, 2017.
56 Non-default alternative dependencies on non-free packages are
57 permitted for packages in main.
60 If upstream provides OpenPGP signatures, including the upstream
61 signing key as ``debian/upstream/signing-key.asc`` in the source
62 package and using the ``pgpsignurlmangle`` option in
63 ``debian/watch`` configuration to indicate how to find the upstream
64 signature for new releases is recommended.
67 Packages should build reproducibly when certain factors are held
68 constant; see 4.15 for the list.
71 Packages are recommended to build reproducibly even when build
72 paths and most environment variables are allowed to vary.
75 Only the dynamic linker may install files to ``/lib64/``.
77 No package for a 64 bit architecture may install files to
78 ``/usr/lib64/`` or any subdirectory.
81 The required behaviour of ``x-terminal-emulator -e`` has been
82 clarified, and updated to replace a false claim about the
83 behaviour of ``xterm``.
85 Programs must support ``-e command`` where ``command`` may include
86 multiple arguments, which must be executed as if the arguments
87 were passed to ``execvp`` directly, bypassing the shell.
89 If this execution fails and ``-e`` has a single argument,
90 ``xterm``'s fallback behaviour of passing ``command`` to the shell
91 is permitted but not required.
96 Released August, 2017.
99 Priorities are now used only for controlling which packages are part
100 of a minimal or standard Debian installation and should be selected
101 based on functionality provided directly to users (so nearly all
102 shared libraries should have a priority of ``optional``). Packages
103 may now depend on packages with a lower priority.
105 The ``extra`` priority has been deprecated and should be treated as
106 equivalent to ``optional``. All ``extra`` priorities should be
107 changed to ``optional``. Packages with a priority of ``optional``
108 may conflict with each other (but packages that both have a priority
109 of ``standard`` or higher still may not conflict).
112 New section documenting the ``Testsuite`` field in Debian source
116 Shared libraries must now invoke ``ldconfig`` by means of triggers,
117 instead of maintscripts.
120 Packages are recommended to use debhelper tools instead of invoking
121 ``update-rc.d`` and ``invoke-rc.d`` directly.
124 Policy's description of how the local system administrator may
125 modify the runlevels at which a daemon is started and stopped, and
126 how init scripts may depend on other init scripts, have been
127 removed. These are now handled by LSB headers.
130 Policy's specification of the console messages that should be
131 emitted by ``init.d`` scripts has been removed. This is now defined
132 by LSB, for sysvinit, and is not expected to be followed by other
136 Packages installing a Free Desktop entry must not also install a
137 Debian menu system entry.
140 The prohibition against depending on environment variables for
141 reasonable defaults is only for programs on the system PATH and only
142 for custom environment variable settings (not, say, a sane PATH).
150 ``config.sub`` and ``config.guess`` should be updated at build time
151 or replaced with the versions from autotools-dev.
154 New ``TARGET`` set of ``dpkg-architecture`` variables and new
155 ``DEB_*_ARCH_BITS`` and ``DEB_*_ARCH_ENDIAN`` variables.
158 New ``DEB_BUILD_OPTIONS`` tag, ``nodoc``, which says to suppress
159 documentation generation (but continue to build all binary packages,
160 even documentation packages, just let them be mostly empty).
163 Automatically-generated debug packages do not need to have a
164 corresponding paragraph in ``debian/control``. (This is existing
165 practice; this Policy update is just clearer about it.)
168 Colons are not permitted in upstream version numbers.
171 New ``Build-Depends-Arch`` and ``Build-Conflicts-Arch`` fields are
175 The recommended package name for shared library development files is
176 now libraryname-dev or librarynameapiversion-dev, not
177 librarynamesoversion-dev.
180 The stable release of Debian supports ``/run``, so packages may now
181 assume that it exists and do not need any special dependency on a
182 version of initscripts.
185 New optional ``try-restart`` standard init script argument, which
186 (if supported) should restart the service if it is already running
187 and otherwise just report success.
190 Support for the ``status`` init script argument is recommended.
193 Packages must not call ``/etc/init.d`` scripts directly even as a
194 fallback, and instead must always use ``invoke-rc.d`` (which is
195 essential and shouldn't require any conditional).
198 Instructions for ``upstart`` integration removed since ``upstart``
199 is no longer maintained in Debian.
202 Packages may not install files in both ``/path`` and ``/usr/path``,
203 and must manage any backward-compatibility symlinks so that they
204 don't break if ``/path`` and ``/usr/path`` are the same directory.
207 Packages should assume device files in ``/dev`` are dynamically
208 managed and don't have to be created by the package. Packages other
209 than those whose purpose is to manage ``/dev`` must not create or
210 remove files there when a dynamic management facility is in use.
211 Named pipes and device files outside of ``/dev`` should normally be
212 created on demand via init scripts, systemd units, or similar
213 mechanisms, but may be created and removed in maintainer scripts if
214 they must be created during package installation.
217 Checking with the base-passwd maintainer is no longer required (or
218 desirable) when creating a new dynamic user or group in a package.
221 Dependencies on \*-doc packages should be at most Recommends
222 (Suggests if they only include documentation in supplemental
226 The Mozilla Public License 1.1 and 2.0 (MPL-1.1 and MPL-2.0) are now
227 included in ``/usr/share/common-licenses`` and do not need to be
228 copied verbatim in the package ``copyright`` file.
231 The ``https`` form of the copyright-format URL is now allowed and
232 preferred in the ``Format`` field.
235 The Perl search path now includes multiarch directories. The vendor
236 directory for architecture-specific modules is now versioned to
240 New ``adventure`` virtual package for implementations of the classic
241 Colossal Cave Adventure game.
244 New ``httpd-wsgi3`` virtual package for Python 3 WSGI-capable HTTP
245 servers. The existing ``httpd-wsgi`` virtual package is for Python 2
246 WSGI-capable HTTP servers.
249 New ``virtual-mysql-client``, ``virtual-mysql-client-core``,
250 ``virtual-mysql-server``, ``virtual-mysql-server-core``, and
251 ``virtual-mysql-testsuite`` virtual packages for MySQL-compatible
257 Released April, 2016.
260 The menu system is deprecated in favor of the FreeDesktop menu
261 standard. New requirements set for FreeDesktop menu entries.
264 New instructions for registering media type handlers with the
265 FreeDesktop system, which automatically synchronizes with mailcap
266 and therefore replaces mailcap registration for packages using
272 Released February, 2016.
275 Symbolic links must not traverse above the root directory.
278 32bit UIDs in the range 65536-4294967293 are reserved for
279 dynamically allocated user accounts.
282 Empty field values in control files are only permitted in the
283 ``debian/control`` file of a source package.
286 ``debian/rules``: required targets must not attempt network access.
289 recommend to ship additional documentation for package ``pkg`` in a
290 separate package ``pkg-doc`` and install it into
291 ``/usr/share/doc/pkg``.
296 Released September, 2014.
299 The FHS is relaxed to allow a subdirectory of ``/usr/lib`` to hold a
300 mixture of architecture-independent and architecture-dependent
301 files, though directories entirely composed of
302 architecture-independent files should be located in ``/usr/share``.
305 The FHS requirement for ``/usr/local/lib64`` to exist if ``/lib64``
306 or ``/usr/lib64`` exists is removed.
309 An FHS exception has been granted for multiarch include files,
310 permitting header files to instead be installed to
311 ``/usr/include/triplet``.
314 Binaries must not be statically linked with the GNU C library, see
315 policy for exceptions.
318 It is clarified that signature appearing in debian/changelog should
319 be the details of the person who prepared this release of the
323 The default web document root is now ``/var/www/html``
326 ``java1-runtime`` and ``java2-runtime`` are removed,
327 ``javaN-runtime`` and ``javaN-runtime-headless`` are added for all N
331 Added ``httpd-wsgi`` for WSGI capable HTTP servers.
334 Perl packages should use the ``%Config`` hash to locate module paths
335 instead of hardcoding paths in ``@INC``.
338 Perl binary modules and any modules installed into
339 ``$Config{vendorarch}`` must depend on the relevant perlapi-\*
345 Released October, 2013.
348 Control data fields must not start with the hyphen character
349 (``-``), to avoid potential confusions when parsing clearsigned
350 control data files that were not properly unescaped.
353 ``Checksums-Sha1`` and ``Checksums-Sha256`` are now mandatory in
357 The ``DM-Upload-Allowed`` field is obsolete. Permissions are now
358 granted via *dak-commands* files.
361 New section documenting the ``Package-List`` field in Debian source
365 New section documenting the ``Package-Type`` field in source package
369 New section documenting the ``Dgit`` field in Debian source control
373 The exception to the FHS for the ``/selinux`` was removed.
376 Packages should remove all obsolete configuration files without
377 local changes during upgrades. The ``dpkg-maintscript-helper`` tool,
378 available from the dpkg package since *Wheezy*, can help with this.
381 The name of the files and directories installed by binary packages
382 must be encoded in UTF-8 and should be restricted to ASCII when
383 possible. In the system PATH, they must be restricted to ASCII.
386 Stop recommending to serve HTML documents from
387 ``/usr/share/doc/package``.
390 Packages distributing Info documents should use install-info's
391 trigger, and do not need anymore to depend on
392 ``dpkg (>= 1.15.4) | install-info``.
395 The ``escape`` capability is now documented.
398 ``mp3-decoder`` and ``mp3-encoder`` are removed.
403 Released August, 2012.
406 New *tasks* archive section.
409 ``build-arch`` and ``build-indep`` are now mandatory targets in
413 New section documenting the ``Vcs-*`` fields, which are already in
414 widespread use. Note the mechanism for specifying the Git branch
415 used for packaging in the Vcs-Git field.
418 The deprecated relations < and > now must not be used.
421 New ``Built-Using`` field, which must be used to document the source
422 packages for any binaries that are incorporated into this package at
423 build time. This is used to ensure that the archive meets license
424 requirements for providing source for all binaries.
427 Policy for dependencies between shared libraries and other packages
428 has been largely rewritten to document the ``symbols`` system and
429 more clearly document handling of shared library ABI changes.
430 ``symbols`` files are now recommended over ``shlibs`` files in most
431 situations. All maintainers of shared library packages should review
432 the entirety of this section.
435 Packages must not assume the ``/run`` directory exists or is usable
436 without a dependency on ``initscripts (>= 2.88dsf-13.3)`` until the
437 stable release of Debian supports ``/run``.
440 Packages including MIME configuration can now rely on triggers and
441 do not need to call update-mime.
444 New section documenting general requirements for alternate init
445 systems and specific requirements for integrating with upstart.
448 All copyright files must be encoded in UTF-8.
453 Released February, 2012.
456 New archive sections *education*, *introspection*, and
457 *metapackages* added.
460 The ``Architecture`` field in ``*.dsc`` files may now contain the
461 value ``any all`` for source packages building both
462 architecture-independent and architecture-dependent packages.
465 If a dependency is restricted to particular architectures, the list
466 of architectures must be non-empty.
469 ``/run`` is allowed as an exception to the FHS and replaces
470 ``/var/run``. ``/run/lock`` replaces ``/var/lock``. The FHS
471 requirements for the older directories apply to these directories as
472 well. Backward compatibility links will be maintained and packages
473 need not switch to referencing ``/run`` directly yet. Files in
474 ``/run`` should be stored in a temporary file system.
477 New section spelling out the requirements for packages that use
478 files in ``/run``, ``/var/run``, or ``/var/lock``. This generalizes
479 information previously only in 9.3.2.
482 Cron job file names must not contain ``.`` or ``+`` or they will be
483 ignored by cron. They should replace those characters with ``_``. If
484 a package provides multiple cron job files in the same directory,
485 they should each start with the package name (possibly modified as
486 above), ``-``, and then some suitable suffix.
489 Packages using doc-base do not need to call install-docs anymore.
492 Packages that declare the same ``conffile`` may see left-over
493 configuration files from each other even if they conflict.
496 The Policy rules around Motif libraries were just a special case of
497 normal rules for non-free dependencies and were largely obsolete, so
498 they have been removed.
501 ``debian/copyright`` is no longer required to list the Debian
502 maintainers involved in the creation of the package (although note
503 that the requirement to list copyright information is unchanged).
506 Version 1.0 of the "Machine-readable ``debian/copyright`` file"
507 specification is included.
510 This separate document has been retired and and its (short) contents
511 merged into Policy section 9.7. There are no changes to the
515 Packages may declare an interest in the perl-major-upgrade trigger
516 to be notified of major upgrades of perl.
519 ``ttf-japanese-{mincho, gothic}`` is renamed to
520 ``fonts-japanese-{mincho, gothic}``.
525 Released April, 2011.
528 Multiple clarifications throughout Policy where "installed" was used
529 and the more precise terms "unpacked" or "configured" were intended.
532 The maintainer address must accept mail from Debian role accounts
533 and the BTS. At least one human must be listed with their personal
534 email address in ``Uploaders`` if the maintainer is a shared email
535 address. The duties of a maintainer are also clearer.
538 All control fields are now classified as simple, folded, or
539 multiline, which governs whether their values must be a single line
540 or may be continued across multiple lines and whether line breaks
544 Parsers are allowed to accept paragraph separation lines containing
545 whitespace, but control files should use completely empty lines.
546 Ordering of paragraphs is significant. Field names must be composed
547 of printable ASCII characters except colon and must not begin with
551 The ``DM-Upload-Allowed`` field is now documented.
554 The system state maintainer scripts can rely upon during each
555 possible invocation is now documented. In several less-common cases,
556 this is stricter than Policy had previously documented. Packages
557 with complex maintainer scripts should be reviewed in light of this
561 The impact on system state when maintainer scripts that are part of
562 a circular dependency are run is now documented. Circular
563 dependencies are now a should not.
566 The system state when ``postinst`` and ``prerm`` scripts are run is
567 now documented, and the documentation of the special case of
568 dependency state for ``postrm`` scripts has been improved.
569 ``postrm`` scripts are required to gracefully skip actions if their
570 dependencies are not available.
573 GNU/Hurd systems are allowed ``/hurd`` and ``/servers`` directories
574 in the root filesystem.
577 Packages installing to architecture-specific subdirectories of
578 ``/usr/lib`` must use the value returned by
579 ``dpkg-architecture -qDEB_HOST_MULTIARCH``, not by
580 ``dpkg-architecture -qDEB_HOST_GNU_TYPE``; this is a path change on
581 i386 architectures and a no-op for other architectures.
584 ``mailx`` is now a virtual package provided by packages that install
585 ``/usr/bin/mailx`` and implement at least the POSIX-required
594 Date-based version components should be given as the four-digit
595 year, two-digit month, and then two-digit day, but may have embedded
599 Maintainer scripts must pass ``--package`` to ``dpkg-divert`` when
600 creating or removing diversions and must not use ``--local``.
603 Only ``dpkg-gencontrol`` supports variable substitution.
604 ``dpkg-genchanges`` (for ``*.changes``) and ``dpkg-source`` (for
608 Architecture restrictions and wildcards are also allowed in binary
609 package relationships provided that the binary package is not
610 architecture-independent.
613 ``Conflicts`` and ``Breaks`` should only be used when there are file
614 conflicts or one package breaks the other, not just because two
615 packages provide similar functionality but don't interfere.
618 The SONAME of a library should change whenever the ABI of the
619 library changes in a way that isn't backward-compatible. It should
620 not change if the library ABI changes are backward-compatible.
621 Discourage bundling shared libraries together in one package.
624 Ada Library Information (``*.ali``) files must be installed
628 Packages should normally not include a ``shlibs.local`` file since
629 we now have complete ``shlibs`` coverage.
632 The SONAME of a library may instead be of the form
633 ``name-major-version.so``.
636 Libtool ``.la`` files should not be installed for public libraries.
637 If they're required (for ``libltdl``, for instance), the
638 ``dependency_libs`` setting should be emptied. Library packages
639 historically including ``.la`` files must continue to include them
640 (with ``dependency_libs`` emptied) until all libraries that depend
641 on that library have removed or emptied their ``.la`` files.
644 Libraries no longer need to be built with ``-D_REENTRANT``, which
645 was an obsolete LinuxThreads requirement. Instead, say explicitly
646 that libraries should be built with threading support and to be
647 thread-safe if the library supports this.
650 ``/bin/sh`` scripts may assume that ``kill`` supports an argument of
651 ``-signal``, that ``kill`` and ``trap`` support the numeric signals
652 listed in the XSI extension, and that signal 13 (SIGPIPE) can be
653 trapped with ``trap``.
656 Use of ``/etc/logrotate.d/package`` for logrotate rules is now
660 Control information files should be owned by ``root:root`` and
661 either mode 644 or mode 755.
664 Packages providing alternatives for ``editor``, ``pager``,
665 ``x-terminal-emulator``, or ``x-window-manager`` should also provide
666 a slave alternative for the corresponding manual page.
669 Cgi-bin executable files may be installed in subdirectories of
670 ``/usr/lib/cgi-bin`` and web servers should serve out executables in
671 those subdirectories.
674 The GPL version 1 is now included in common-licenses and should be
675 referenced from there instead of included in the ``copyright`` file.
683 The required format for the date in a changelog entry and in the
684 Date control field is now precisely specified.
687 A control paragraph must not contain more than one instance of a
688 particular field name.
691 The ``Checksums-Sha1`` and ``Checksums-Sha256`` fields in ``*.dsc``
692 and ``*.changes`` files are now documented and recommended.
695 The ``Format`` field of ``.changes`` files is now 1.8. The
696 ``Format`` field syntax for source package ``.dsc`` files allows a
697 subtype in parentheses, and it is used for a different purpose than
698 the ``Format`` field for ``.changes`` files.
701 The syntax of the ``Maintainer`` field is now must rather than
705 The comma separating entries in ``Uploaders`` is now must rather
709 Architecture wildcards may be used in addition to specific
710 architectures in ``debian/control`` and ``*.dsc`` Architecture
711 fields, and in architecture restrictions in build relationships.
714 Maintainer scripts are no longer guaranteed to run with a
715 controlling terminal and must be able to fall back to noninteractive
716 behavior (debconf handles this). Maintainer scripts may abort if
717 there is no controlling terminal and no reasonable default for a
718 high-priority question, but should avoid this if possible.
721 ``Breaks`` should be used with ``Replaces`` for moving files between
725 ``Breaks`` should normally be used instead of ``Conflicts`` for
726 transient issues and moving files between packages. New
727 documentation of when each should be used.
730 Use ``Conflicts`` with ``Provides`` if only one provider of a
731 virtual facility can be installed at a time.
734 All shared library development files are no longer required to be in
735 the ``-dev`` package, only be available when the ``-dev`` package is
736 installed. This allows the ``-dev`` package to be split as long as
737 it depends on the additional packages.
740 The UID range of user accounts is extended to 1000-59999.
743 ``init.d`` scripts are a possible exception from the normal
744 requirement to use ``set -e`` in each shell script.
747 The UCB BSD license was removed from the list of licenses that
748 should be referenced from ``/usr/share/common-licenses/BSD``. It
749 should instead be included directly in ``debian/copyright``,
750 although it will still be in common-licenses for the time being.
753 ``SETTITLE`` is now documented (it has been supported for some
754 time). ``SETTITLE`` is like ``TITLE`` but takes a template instead
755 of a string to allow translation.
758 perl-base now provides perlapi-abiname instead of a package based
759 solely on the Perl version. Perl packages must now depend on
760 perlapi-$Config{debian\_abi}, falling back on ``$Config{version}``
761 if ``$Config{debian_abi}`` is not set.
764 Packages using ``Makefile.PL`` should use ``DESTDIR`` rather than
765 ``PREFIX`` to install into the package staging area. ``PREFIX`` only
766 worked due to a Debian-local patch.
771 Released January, 2010.
774 An FHS exception has been granted for multiarch libraries.
775 Permitting files to instead be installed to ``/lib/triplet`` and
776 ``/usr/lib/triplet`` directories.
779 Packages may not contain named pipes and should instead create them
780 in postinst and remove them in prerm or postrm.
783 ``/sys`` and ``/selinux`` directories are explicitly allowed as an
784 exception to the FHS.
789 Released August, 2009.
792 DEB\_\*\_ARCH\_CPU and DEB\_\*\_ARCH\_OS variables are now
793 documented and recommended over GNU-style variables for that
797 Source package Architecture fields may contain *all* in combination
798 with other architectures. Clarify when *all* and *any* may be used
799 in different versions of the field.
802 The Debian archive software does not support uploading to multiple
803 distributions with one ``*.changes`` file.
806 The Binary field may span multiple lines.
809 Shared library packages are no longer allowed to install libraries
810 in a non-standard location and modify ``ld.so.conf``. Packages
811 should either be installed in a standard library directory or
812 packages using them should be built with RPATH.
815 Installation directories for X programs have been clarified.
816 Packages are no longer required to pre-depend on x11-common before
817 installing into ``/usr/include/X11`` and ``/usr/lib/X11``.
820 Manual pages are no longer required to contain only characters
821 representable in the legacy encoding for that language.
824 Localized man pages should either be kept up-to-date with the
825 original version or warn that they're not up-to-date, either with
826 warning text or by showing missing or changed portions in the
830 install-info is now handled via triggers so packages no longer need
831 to invoke it in maintainer scripts. Info documents should now have
832 directory sections and entries in the document. Packages containing
833 info documents should add a dependency to support partial upgrades.
836 The requirement for Perl modules to have a versioned Depend and
837 Build-Depend on ``perl >= 5.6.0-16`` has been removed.
845 The list of archive sections has been significantly expanded. See
846 `this debian-devel-announce
847 message <http://lists.debian.org/debian-devel-announce/2009/03/msg00010.html>`__
848 for the list of new sections and rules for how to categorize
852 All packages must use debconf or equivalent for user prompting,
853 though essential packages or their dependencies may also fall back
857 The requirements for source package names are now explicitly spelled
861 Legacy XFree86 servers no longer get a special exception from the
862 FHS permitting ``/etc/X11/XF86Config-4``.
865 Removed obsolete dependency requirements for packages that use
869 Speedo fonts are now deprecated. The X backend was disabled starting
873 The GNU Free Documentation License version 1.3 is included in
874 common-licenses and should be referenced from there.
879 Released March, 2009.
882 Care should be taken when adding functionality to essential and such
883 additions create an obligation to support that functionality in
884 essential forever unless significant work is done.
887 Changelog files must be encoded in UTF-8.
890 Some format requirements for changelog files are now "must" instead
894 Alternative changelog formats have been removed. Debian only
895 supports one changelog format for the Debian Archive.
898 New nocheck option for DEB\_BUILD\_OPTIONS indicating any build-time
899 test suite provided by the package should not be run.
902 All control files must be encoded in UTF-8.
905 ``debian/control`` allows comment lines starting with # with no
906 preceding whitespace.
909 Init scripts ending in .sh are not handled specially. They are not
910 sourced and are not guaranteed to be run by ``/bin/sh`` regardless
911 of the #! line. This brings Policy in line with the long-standing
912 behavior of the init system in Debian.
915 The start action of an init script must exit successfully and not
916 start the daemon again if it's already running.
919 ``/var/run`` and ``/var/lock`` may be mounted as temporary
920 filesystems, and init scripts must therefore create any necessary
921 subdirectories dynamically.
924 ``/bin/sh`` scripts may assume that local can take multiple variable
925 arguments and supports assignment.
928 User mailboxes may be mode 600 and owned by the user rather than
929 mode 660, owned by user, and group mail.
937 The base section has been removed. contrib and non-free have been
938 removed from the section list; they are only categories. The base
939 system is now defined by priority.
942 If ``dpkg-source -x`` doesn't provide the source that will be
943 compiled, a debian/rules patch target is recommended and should do
944 whatever else is necessary.
947 Standardized the format of DEB\_BUILD\_OPTIONS. Specified permitted
948 characters for tags, required that tags be whitespace-separated,
949 allowed packages to assume non-conflicting tags, and required
950 unknown flags be ignored.
953 Added parallel=n to the standardized DEB\_BUILD\_OPTIONS tags,
954 indicating that a package should be built using up to n parallel
955 processes if the package supports it
958 Debian packages should not use convenience copies of code from other
959 packages unless the included package is explicitly intended to be
963 If dpkg-source -x doesn't produce source ready for editing and
964 building with dpkg-buildpackage, packages should include a
965 ``debian/README.source`` file explaining how to generate the patched
966 source, add a new modification, and remove an existing modification.
967 This file may also be used to document packaging a new upstream
968 release and any other complexity of the Debian build process.
971 The Uploaders field in debian/control may be wrapped.
974 An empty Debian revision is equivalent to a Debian revision of 0 in
978 New Homepage field for upstream web sites.
981 The Breaks field declares that this package breaks another and
982 prevents installation of the breaking package unless the package
983 named in Breaks is deconfigured first. This field should not be used
984 until the dpkg in Debian stable supports it.
987 Clarify which files should go into a shared library package, into a
988 separate package, or into the -dev package. Suggest -tools instead
989 of -runtime for runtime support programs, since that naming is more
993 Files in ``/etc/cron.{hourly,daily,weekly,monthly}`` must be
994 configuration files (upgraded from should). Mention the hourly
998 Packages providing ``/etc/X11/Xresources`` files need not conflict
999 with ``xbase (<< 3.3.2.3a-2)``, which is long-obsolete.
1002 Manual pages in locale-specific directories should use either the
1003 legacy encoding for that directory or UTF-8. Country names should
1004 not be included in locale-specific manual page directories unless
1005 indicating a significant difference in the language. All characters
1006 in the manual page source should be representable in the legacy
1007 encoding for a locale even if the man page is encoded in UTF-8.
1010 The Apache 2.0 license is now in common-licenses and should be
1011 referenced rather than quoted in ``debian/copyright``.
1014 Packages in contrib and non-free should state in the copyright file
1015 that the package is not part of Debian GNU/Linux and briefly explain
1019 Underscore (``_``) is allowed in debconf template names.
1024 Released December, 2007.
1027 Package version numbers may contain tildes, which sort before
1028 anything, even the end of a part.
1031 Scripts may assume that ``/bin/sh`` supports local (at a basic
1032 level) and that its test builtin (if any) supports -a and -o binary
1036 The substitution variable ${binary:Version} should be used in place
1037 of ${Source-Version} for dependencies between packages of the same
1041 Substantial reorganization and renaming of sections in the Debian
1042 menu structure. Packages with menu entries should be reviewed to see
1043 if the menu section has been renamed or if one of the new sections
1044 would be more appropriate.
1047 The Source field in a .changes file may contain a version number in
1051 The acceptable values for the Urgency field are low, medium, high,
1052 critical, or emergency.
1055 The shlibs file now allows an optional type field, indicating the
1056 type of package for which the line is valid. The only currently
1057 supported type is udeb, used with packages for the Debian Installer.
1060 Packages following the Debian Configuration management specification
1061 must allow for translation of their messages by using a
1062 gettext-based system such as po-debconf.
1065 GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should be
1066 referenced rather than quoted in debian/copyright.
1071 Released October, 2006.
1073 This release broke the normal rule against introducing normative changes
1074 without changing the major patch level.
1077 Maintainer scripts must not be world writeable (up from a should to
1083 Released April, 2006.
1086 Revert the cgi-lib change.
1091 Released April, 2006.
1094 It is now possible to create shared libraries without relocatable
1095 code (using -fPIC) in certain exceptional cases, provided some
1096 procedures are followed, and for creating static libraries with
1097 relocatable code (again, using -fPIC). Discussion on
1098 debian-devel@lists.debian.org, getting a rough consensus, and
1099 documenting it in README.Debian constitute most of the process.
1102 Packages should install any relevant files into the directories
1103 ``/usr/include/X11/`` and ``/usr/lib/X11/``, but if they do so, they
1104 must pre-depend on ``x11-common (>= 1:7.0.0)``
1109 Released April, 2006.
1112 Packages shipping web server CGI files are expected to install them
1113 in ``/usr/lib/cgi-lib/`` directories. This location change perhaps
1114 should be documented in NEWS
1117 Web server packages should include a standard scriptAlias of cgi-lib
1118 to ``/usr/lib/cgi-lib``.
1121 The version of FHS mandated by policy has been upped to 2.3. There
1122 should be no changes required for most packages, though new top
1123 level directories ``/media``, ``/srv``, etc. may be of interest.
1126 All fields, apart from the Uploaders field, in the control file are
1127 supposed to be a single logical line, which may be spread over
1128 multiple physical lines (newline followed by space is elided).
1129 However, any parser for the control file must allow the Uploaders
1130 field to be spread over multiple physical lines as well, to prepare
1134 When scripts are installed into a directory in the system PATH, the
1135 script name should not include an extension that denotes the
1136 scripting language currently used to implement it.
1139 packages that invoke initscripts now must use invoke-rc.d to do so
1140 since it also pays attention to run levels and other local
1143 11.8.5.2, 11.8.7, etc
1144 We no longer use ``/usr/X11R6``, since we have migrated away to
1145 using Xorg paths. This means, for one thing, fonts live in
1146 ``/usr/share/fonts/X11/`` now, and ``/usr/X11R6`` is gone.
1151 Released June, 2005.
1153 Recommend doc-base, and not menu, for registering package
1157 Run time support programs should live in subdirectories of
1158 ``/usr/lib/`` or ``/usr/share``, and preferably the shared lib is
1159 named the same as the package name (to avoid name collisions).
1162 It is recommended that HTTP servers provide an alias /images to
1163 allow packages to share image files with the web server
1168 Released August, 2003.
1171 Prompting the user should be done using debconf. Non debconf user
1172 prompts are now deprecated.
1177 Released July, 2003.
1179 Restructuring caused shifts in section numbers and bumping of the
1180 minor version number.
1182 Many packaging manual appendices that were integrated into policy
1183 sections are now empty, and replaced with links to the Policy. In
1184 particular, the appendices that included the list of control fields
1185 were updated (new fields like Closes, Changed-By were added) and the
1186 list of fields for each of control, .changes and .dsc files is now
1187 in Policy, and they're marked mandatory, recommended or optional
1188 based on the current practice and the behavior of the deb-building
1191 Elimination of needlessly deep section levels, primarily in the
1192 chapter Debian Archive, from which two new chapters were split out,
1193 Binary packages and Source packages. What remained was reordered
1194 properly, that is, some sects became sects etc.
1196 Several sections that were redundant, crufty or simply not designed
1197 with any sort of vision, were rearranged according to the formula
1198 that everything should be either in the same place or properly
1199 interlinked. Some things remained split up between different
1200 chapters when they talked about different aspects of files: their
1201 content, their syntax, and their placement in the file system. In
1202 particular, see the new sections about changelog files.
1205 Added Games/Simulation and Apps/Education to menu sub-policy
1208 Debian changelogs should be UTF-8 encoded.
1211 shared libraries must be linked against all libraries that they use
1212 symbols from in the same way that binaries are.
1215 build-depends-indep need not be satisfied during clean target.
1223 packages providing the x-terminal-emulator virtual package ought to
1224 ensure that they interpret the command line exactly like xterm does.
1227 Window managers compliant with the Window Manager Specification
1228 Project may add 40 points for ranking in the alternatives
1233 Released March, 2003.
1236 The section describing the Description: package field once again has
1237 full details of the long description format.
1240 Clarified that if a package has non-build-essential
1241 build-dependencies, it should have them listed in the Build-Depends
1242 and related fields (i.e. it's not merely optional).
1245 When asked to restart a service that isn't already running, the init
1246 script should start the service.
1249 If the purpose of a package is to provide examples, then the example
1250 files can be installed into ``/usr/share/doc/package`` (rather than
1251 ``/usr/share/doc/package/examples``).
1256 Released November, 2002.
1259 It is no longer necessary to keep a log of changes to the upstream
1260 sources in the copyright file. Instead, all such changes should be
1261 documented in the changelog file.
1264 Build-Depends, Build-Conflicts, Build-Depends-Indep, and
1265 Build-Conflicts-Indep must also be satisfied when the clean target
1269 A new Apps/Science menu section is available
1272 debconf specification cleared up, various changes.
1275 It is no longer recommended to create symlinks from nonexistent
1276 manual pages to undocumented(7). Missing manual pages for programs
1282 Released August, 2002.
1284 Packages no longer have to ask permission to call MAKEDEV in
1285 postinst, merely notifying the user ought to be enough.
1288 cryptographic software may now be included in the main archive.
1291 task packages are no longer permitted; tasks are now created by a
1292 special Tasks: field in the control file.
1295 window managers that support netwm can now add 20 points when they
1296 add themselves as an alternative for ``/usr/bin/x-window-manager``
1299 The default compilation options have now changed, one should provide
1300 debugging symbols in all cases, and optionally step back
1301 optimization to -O0, depending on the DEB\_BUILD\_OPTIONS
1302 environment variable.
1305 Added mention of build-arch, build-indep, etc, in describing the
1306 relationships with Build-Depends, Build-Conflicts,
1307 Build-Depends-Indep, and Build-Conflicts-Indep. May need to
1308 review the new rules.
1311 Changed rules on how, and when, to invoke ldconfig in maintainer
1312 scripts. Long rationale.
1314 *Added the last note in 3.5.6 upgrading checklist item regarding build
1315 rules, please see below*
1320 Released July, 2001.
1323 Emacs and TeX are no longer mandated by policy to be priority
1327 Programs that access docs need to do so via ``/usr/share/doc``, and
1328 not via ``/usr/doc/`` as was the policy previously
1331 Putting documentation in ``/usr/doc`` versus ``/usr/share/doc`` is
1332 now a "serious" policy violation.
1335 For web servers, one should not provide non-local access to the
1336 ``/usr/share/doc`` hierarchy. If one can't provide access controls
1337 for the http://localhost/doc/ directory, then it is preferred that
1338 one ask permission to expose that information during the install.
1341 There are new rules for build-indep/build-arch targets and there is
1342 a new Build-Depend-Indep semantic.
1350 Manpages should not rely on header information to have alternative
1351 manpage names available; it should only use symlinks or .so pages to
1354 *Clarified note in 3.5.3.0 upgrading checklist regarding examples
1355 and templates: this refers only to those examples used by scripts;
1356 see section 10.7.3 for the whole story*
1358 Included a new section 10.9.1 describing the use of
1359 dpkg-statoverride; this does not have the weight of policy
1361 Clarify Standards-Version: you don't need to rebuild your packages
1362 just to change the Standards-Version!
1365 Plugins are no longer bound by all the rules of shared libraries
1367 X Windows related things:
1369 Clarification of priority levels of X Window System related
1373 Rules for defining x-terminal-emulator improved
1376 X Font policy rewritten: you must read this if you provide fonts
1377 for the X Window System
1380 Packages must not ship ``/usr/X11R6/lib/X11/app-defaults/``
1383 X-related packages should usually use the regular FHS locations;
1384 imake-using packages are exempted from this
1387 OpenMotif linked binaries have the same rules as
1388 OSF/Motif-linked ones
1393 Released April, 2001.
1396 The system-wide mail directory is now /var/mail, no longer
1397 /var/spool/mail. Any packages accessing the mail spool should access
1398 it via /var/mail and include a suitable Depends field;
1401 The perl policy is now part of Debian policy proper. Perl programs
1402 and modules should follow the current Perl policy
1407 Released April, 2001.
1410 Build-Depends arch syntax has been changed to be less ambiguous.
1411 This should not affect any current packages
1414 Examples and templates files for use by scripts should now live in
1415 ``/usr/share/<package>`` or ``/usr/lib/<package>``, with symbolic
1416 links from ``/usr/share/doc/<package>/examples`` as needed
1421 Released February, 2001.
1424 X app-defaults directory has moved from
1425 ``/usr/X11R6/lib/X11/app-defaults`` to ``/etc/X11/app-defaults``
1430 Released February, 2001.
1433 dpkg-shlibdeps now uses objdump, so shared libraries have to be run
1434 through dpkg-shlibdeps as well as executables
1439 Released January, 2001.
1442 Font packages for the X Window System must now declare a dependency
1443 on ``xutils (>= 4.0.2)``
1448 Released January, 2001.
1450 This release broke the normal rule against introducing normative changes
1451 without changing the major patch level.
1454 Daemon startup scripts in ``/etc/init.d/`` should not contain
1455 modifiable parameters; these should be moved to a file in
1459 Files in ``/usr/share/doc`` must not be referenced by any program.
1460 If such files are needed, they must be placed in
1461 ``/usr/share/<package>/``, and symbolic links created as required in
1462 ``/usr/share/doc/<package>/``
1464 Much of the packaging manual has now been imported into the policy
1470 Released August, 2000.
1473 A package of priority standard or higher may provide two binaries,
1474 one compiled with support for the X Window System, and the other
1480 Released August, 2000.
1483 By default executables should not be built with the debugging option
1484 -g. Instead, it is recommended to support building the package with
1485 debugging information optionally.
1488 Policy for packages where the upstream uses HTML changelog files has
1489 been expanded. In short, a plain text changelog file should always
1490 be generated for the upstream changes
1492 Please note that the new release of the X window system (3.2) shall
1493 probably need sweeping changes in policy
1495 Policy for packages providing the following X-based features has
1499 X server (virtual package xserver)
1502 X terminal emulator (virtual package x-terminal-emulator)
1505 X window manager (virtual package x-window-manager, and
1506 ``/usr/bin/x-window-manager`` alternative, with priority
1507 calculation guidelines)
1510 X fonts (this section has been written from scratch)
1513 X application defaults
1516 Policy for packages using the X Window System and FHS issues has
1520 No package may contain or make hard links to conffiles
1523 Noted that newer dpkg versions do not require extreme care in always
1524 creating the shared lib before the symlink, so the unpack order be
1530 Released November, 1999.
1533 Correction to semantics of architecture lists in Build-Depends etc.
1534 Should not affect many packages
1539 Released October, 1999.
1542 ``/usr/doc/<package>`` has to be a symlink pointing to
1543 ``/usr/share/doc/<package>``, to be maintained by postinst and prerm
1547 Introduced source dependencies (Build-Depends, etc.)
1550 ``/etc/rc.boot`` has been deprecated in favour of ``/etc/rcS.d``.
1551 (Packages should not be touching this directory, but should use
1552 update-rc.d instead)
1555 update-rc.d is now the *only* allowable way of accessing the
1556 ``/etc/rc?.d/[SK]??*`` links. Any scripts which manipulate them
1557 directly must be changed to use update-rc.d instead. (This is
1558 because the file-rc package handles this information in an
1562 Architecture-specific examples go in ``/usr/lib/<package>/examples``
1563 with symlinks from ``/usr/share/doc/<package>/examples/*`` or from
1564 ``/usr/share/doc/<package>/examples`` itself
1567 Updated FHS to a 2.1 draft; this reverts ``/var/state`` to
1571 Added MIME sub-policy document
1574 VISUAL is allowed as a (higher priority) alternative to EDITOR
1577 Modified liblockfile description, which affects mailbox-accessing
1578 programs. Please see the policy document for details
1581 If a package provides a changelog in HTML format, a text-only
1582 version should also be included. (Such a version may be prepared
1583 using ``lynx -dump -nolist``.)
1586 Description of how to handle version numbers based on dates added
1591 Released July, 1999.
1594 Added the clarification that the .la files are essential for the
1595 packages using libtool's libltdl library, in which case the .la
1596 files must go in the run-time library package
1601 Released June, 1999.
1604 Debian formally moves from the FSSTND to the FHS. This is a major
1605 change, and the implications of this move are probably not all
1609 Only 3 digits of the Standards version need be included in control
1610 files, though all four digits are still permitted.
1613 The location of the GPL has changed to
1614 ``/usr/share/common-licenses``. This may require changing the
1615 copyright files to point to the correct location of the GPL and
1616 other major licenses
1619 Packages that use libtool to create shared libraries must include
1620 the .la files in the -dev packages
1623 Use logrotate to rotate log files
1626 section 5.8 has been rewritten (Programs for the X Window System)
1629 There is now an associated menu policy, in a separate document, that
1630 carries the full weight of Debian policy
1633 Programs which need to modify the files ``/var/run/utmp``,
1634 ``/var/log/wtmp`` and ``/var/log/lastlog`` must be installed setgid
1640 Released October, 1998.
1642 *Please note that section numbers below this point may not match the
1643 current Policy Manual.*
1645 - Rearranged the manual to create a new Section 4, Files
1647 - Section 3.3 ("Files") was moved to Section 4. The Sections that
1648 were Section 4 and Section 5 were moved down to become Section 5
1651 - What was Section 5.5 ("Log files") is now a subsection of the new
1652 Section 4 ("Files"), becoming section 4.8, placed after
1653 "Configuration files", moving the Section 4.8 ("Permissions and
1654 owners") to Section 4.9. All subsections of the old Section 5
1655 after 5.5 were moved down to fill in the number gap.
1657 - Modified the section about changelog files to accommodate upstream
1658 changelogs which were formatted as HTML. These upstream changelog
1659 files should now be accessible as
1660 ``/usr/doc/package/changelog.html.gz``
1662 - Symlinks are permissible to link the real, or upstream, changelog
1663 name to the Debian mandated name.
1665 - Clarified that HTML documentation should be present in some package,
1666 though not necessarily the main binary package.
1668 - Corrected all references to the location of the copyright files. The
1669 correct location is ``/usr/doc/package/copyright``
1671 - Ratified the architecture specification strings to cater to the HURD.
1676 Released April, 1998.
1678 Updated section 3.3.5 Symbolic links
1679 symbolic links within a toplevel directory should be relative,
1680 symbolic links between toplevel directories should be absolute (cf.,
1681 Policy Weekly Issue#6, topic 2)
1683 Updated section 4.9 Games
1684 manpages for games should be installed in ``/usr/man/man6`` (cf.,
1685 Policy Weekly Issue#6, topic 3)
1687 Updated Chapter 12 Shared Libraries
1688 ldconfig must be called in the postinst script if the package
1689 installs shared libraries (cf., Policy Weekly Issue #6,
1695 Released January, 1998
1697 Updated section 3.3.4 Scripts
1698 - /bin/sh may be any POSIX compatible shell
1700 - scripts including bashisms have to specify ``/bin/bash`` as
1703 - scripts which create files in world-writable directories (e.g.,
1704 in ``/tmp``) should use tempfile or mktemp for creating the
1707 Updated section 3.3.5 Symbolic Links
1708 symbolic links referencing compressed files must have the same file
1709 extension as the referenced file
1711 Updated section 3.3.6 Device files
1712 ``/dev/tty*`` serial devices should be used instead of ``/dev/cu*``
1714 Updated section 3.4.2 Writing the scripts in ``/etc/init.d``
1715 - all ``/etc/init.d`` scripts have to provide the following
1716 options: start, stop, restart, force-reload
1718 - the reload option is optional and must never stop and restart the
1721 Updated section 3.5 Cron jobs
1722 cron jobs that need to be executed more often than daily should be
1723 installed into ``/etc/cron.d``
1725 Updated section 3.7 Menus
1726 removed section about how to register HTML docs to \`menu' (the
1727 corresponding section in 4.4, Web servers and applications, has been
1728 removed in policy 2.2.0.0 already, so this one was obsolete)
1730 New section 3.8 Keyboard configuration
1731 details about how the backspace and delete keys should be handled
1733 New section 3.9 Environment variables
1734 no program must depend on environment variables to get a reasonable
1735 default configuration
1737 New section 4.6 News system configuration
1738 ``/etc/news/organization`` and ``/etc/news/server`` should be
1739 supported by all news servers and clients
1741 Updated section 4.7 Programs for the X Window System
1742 - programs requiring a non-free Motif library should be provided as
1743 foo-smotif and foo-dmotif package
1745 - if lesstif works reliably for such program, it should be linked
1746 against lesstif and not against a non-free Motif library
1748 Updated section 4.9 Games
1749 games for X Windows have to be installed in ``/usr/games``, just as
1755 Released September, 1997.
1757 - new section \`4.2 Daemons' including rules for ``/etc/services``,
1758 ``/etc/protocols``, ``/etc/rpc``, and ``/etc/inetd.conf``
1760 - updated section about \`Configuration files': packages may not touch
1761 other packages' configuration files
1763 - MUAs and MTAs have to use liblockfile
1768 Released July, 1997.
1770 - added section 4.1 \`Architecture specification strings': use
1771 <arch>-linux where <arch> is one of the following: i386, alpha, arm,
1772 m68k, powerpc, sparc.
1774 - detailed rules for ``/usr/local``
1778 - editor/pager policy
1784 - don't install shared libraries as executable
1786 - app-defaults files may not be conffiles
1791 Released March, 1997.
1793 - two programs with different functionality must not have the same name
1797 - "Standard for Console Messages"
1799 - Libraries should be compiled with ``-D_REENTRANT``
1801 - Libraries should be stripped with ``strip --strip-unneeded``
1806 Released November, 1996.
1808 - Some changes WRT shared libraries
1813 Released September, 1996.
1815 - No hard links in source packages
1817 - Do not use ``dpkg-divert`` or ``update-alternatives`` without
1820 - Shared libraries must be installed stripped
1825 Released August, 1996.
1827 - Upstream changelog must be installed too