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 The shebang at the top of Perl command scripts must be
49 ``#!/usr/bin/perl``. (Previously, this was a 'should' rather than
55 Released September, 2017.
58 debian/changelog must exist in source packages.
61 The canonical non-existent home directory is ``/nonexistent``.
66 Released August, 2017.
69 Non-default alternative dependencies on non-free packages are
70 permitted for packages in main.
73 If upstream provides OpenPGP signatures, including the upstream
74 signing key as ``debian/upstream/signing-key.asc`` in the source
75 package and using the ``pgpsigurlmangle`` option in
76 ``debian/watch`` configuration to indicate how to find the upstream
77 signature for new releases is recommended.
80 Packages should build reproducibly when certain factors are held
81 constant; see 4.15 for the list.
84 Packages are recommended to build reproducibly even when build
85 paths and most environment variables are allowed to vary.
88 Only the dynamic linker may install files to ``/lib64/``.
90 No package for a 64 bit architecture may install files to
91 ``/usr/lib64/`` or any subdirectory.
94 The required behaviour of ``x-terminal-emulator -e`` has been
95 clarified, and updated to replace a false claim about the
96 behaviour of ``xterm``.
98 Programs must support ``-e command`` where ``command`` may include
99 multiple arguments, which must be executed as if the arguments
100 were passed to ``execvp`` directly, bypassing the shell.
102 If this execution fails and ``-e`` has a single argument,
103 ``xterm``'s fallback behaviour of passing ``command`` to the shell
104 is permitted but not required.
109 Released August, 2017.
112 Priorities are now used only for controlling which packages are part
113 of a minimal or standard Debian installation and should be selected
114 based on functionality provided directly to users (so nearly all
115 shared libraries should have a priority of ``optional``). Packages
116 may now depend on packages with a lower priority.
118 The ``extra`` priority has been deprecated and should be treated as
119 equivalent to ``optional``. All ``extra`` priorities should be
120 changed to ``optional``. Packages with a priority of ``optional``
121 may conflict with each other (but packages that both have a priority
122 of ``standard`` or higher still may not conflict).
125 New section documenting the ``Testsuite`` field in Debian source
129 Shared libraries must now invoke ``ldconfig`` by means of triggers,
130 instead of maintscripts.
133 Packages are recommended to use debhelper tools instead of invoking
134 ``update-rc.d`` and ``invoke-rc.d`` directly.
137 Policy's description of how the local system administrator may
138 modify the runlevels at which a daemon is started and stopped, and
139 how init scripts may depend on other init scripts, have been
140 removed. These are now handled by LSB headers.
143 Policy's specification of the console messages that should be
144 emitted by ``init.d`` scripts has been removed. This is now defined
145 by LSB, for sysvinit, and is not expected to be followed by other
149 Packages installing a Free Desktop entry must not also install a
150 Debian menu system entry.
153 The prohibition against depending on environment variables for
154 reasonable defaults is only for programs on the system PATH and only
155 for custom environment variable settings (not, say, a sane PATH).
163 ``config.sub`` and ``config.guess`` should be updated at build time
164 or replaced with the versions from autotools-dev.
167 New ``TARGET`` set of ``dpkg-architecture`` variables and new
168 ``DEB_*_ARCH_BITS`` and ``DEB_*_ARCH_ENDIAN`` variables.
171 New ``DEB_BUILD_OPTIONS`` tag, ``nodoc``, which says to suppress
172 documentation generation (but continue to build all binary packages,
173 even documentation packages, just let them be mostly empty).
176 Automatically-generated debug packages do not need to have a
177 corresponding paragraph in ``debian/control``. (This is existing
178 practice; this Policy update is just clearer about it.)
181 Colons are not permitted in upstream version numbers.
184 New ``Build-Depends-Arch`` and ``Build-Conflicts-Arch`` fields are
188 The recommended package name for shared library development files is
189 now libraryname-dev or librarynameapiversion-dev, not
190 librarynamesoversion-dev.
193 The stable release of Debian supports ``/run``, so packages may now
194 assume that it exists and do not need any special dependency on a
195 version of initscripts.
198 New optional ``try-restart`` standard init script argument, which
199 (if supported) should restart the service if it is already running
200 and otherwise just report success.
203 Support for the ``status`` init script argument is recommended.
206 Packages must not call ``/etc/init.d`` scripts directly even as a
207 fallback, and instead must always use ``invoke-rc.d`` (which is
208 essential and shouldn't require any conditional).
211 Instructions for ``upstart`` integration removed since ``upstart``
212 is no longer maintained in Debian.
215 Packages may not install files in both ``/path`` and ``/usr/path``,
216 and must manage any backward-compatibility symlinks so that they
217 don't break if ``/path`` and ``/usr/path`` are the same directory.
220 Packages should assume device files in ``/dev`` are dynamically
221 managed and don't have to be created by the package. Packages other
222 than those whose purpose is to manage ``/dev`` must not create or
223 remove files there when a dynamic management facility is in use.
224 Named pipes and device files outside of ``/dev`` should normally be
225 created on demand via init scripts, systemd units, or similar
226 mechanisms, but may be created and removed in maintainer scripts if
227 they must be created during package installation.
230 Checking with the base-passwd maintainer is no longer required (or
231 desirable) when creating a new dynamic user or group in a package.
234 Dependencies on \*-doc packages should be at most Recommends
235 (Suggests if they only include documentation in supplemental
239 The Mozilla Public License 1.1 and 2.0 (MPL-1.1 and MPL-2.0) are now
240 included in ``/usr/share/common-licenses`` and do not need to be
241 copied verbatim in the package ``copyright`` file.
244 The ``https`` form of the copyright-format URL is now allowed and
245 preferred in the ``Format`` field.
248 The Perl search path now includes multiarch directories. The vendor
249 directory for architecture-specific modules is now versioned to
253 New ``adventure`` virtual package for implementations of the classic
254 Colossal Cave Adventure game.
257 New ``httpd-wsgi3`` virtual package for Python 3 WSGI-capable HTTP
258 servers. The existing ``httpd-wsgi`` virtual package is for Python 2
259 WSGI-capable HTTP servers.
262 New ``virtual-mysql-client``, ``virtual-mysql-client-core``,
263 ``virtual-mysql-server``, ``virtual-mysql-server-core``, and
264 ``virtual-mysql-testsuite`` virtual packages for MySQL-compatible
270 Released April, 2016.
273 The menu system is deprecated in favor of the FreeDesktop menu
274 standard. New requirements set for FreeDesktop menu entries.
277 New instructions for registering media type handlers with the
278 FreeDesktop system, which automatically synchronizes with mailcap
279 and therefore replaces mailcap registration for packages using
285 Released February, 2016.
288 Symbolic links must not traverse above the root directory.
291 32bit UIDs in the range 65536-4294967293 are reserved for
292 dynamically allocated user accounts.
295 Empty field values in control files are only permitted in the
296 ``debian/control`` file of a source package.
299 ``debian/rules``: required targets must not attempt network access.
302 recommend to ship additional documentation for package ``pkg`` in a
303 separate package ``pkg-doc`` and install it into
304 ``/usr/share/doc/pkg``.
309 Released September, 2014.
312 The FHS is relaxed to allow a subdirectory of ``/usr/lib`` to hold a
313 mixture of architecture-independent and architecture-dependent
314 files, though directories entirely composed of
315 architecture-independent files should be located in ``/usr/share``.
318 The FHS requirement for ``/usr/local/lib64`` to exist if ``/lib64``
319 or ``/usr/lib64`` exists is removed.
322 An FHS exception has been granted for multiarch include files,
323 permitting header files to instead be installed to
324 ``/usr/include/triplet``.
327 Binaries must not be statically linked with the GNU C library, see
328 policy for exceptions.
331 It is clarified that signature appearing in debian/changelog should
332 be the details of the person who prepared this release of the
336 The default web document root is now ``/var/www/html``
339 ``java1-runtime`` and ``java2-runtime`` are removed,
340 ``javaN-runtime`` and ``javaN-runtime-headless`` are added for all N
344 Added ``httpd-wsgi`` for WSGI capable HTTP servers.
347 Perl packages should use the ``%Config`` hash to locate module paths
348 instead of hardcoding paths in ``@INC``.
351 Perl binary modules and any modules installed into
352 ``$Config{vendorarch}`` must depend on the relevant perlapi-\*
358 Released October, 2013.
361 Control data fields must not start with the hyphen character
362 (``-``), to avoid potential confusions when parsing clearsigned
363 control data files that were not properly unescaped.
366 ``Checksums-Sha1`` and ``Checksums-Sha256`` are now mandatory in
370 The ``DM-Upload-Allowed`` field is obsolete. Permissions are now
371 granted via *dak-commands* files.
374 New section documenting the ``Package-List`` field in Debian source
378 New section documenting the ``Package-Type`` field in source package
382 New section documenting the ``Dgit`` field in Debian source control
386 The exception to the FHS for the ``/selinux`` was removed.
389 Packages should remove all obsolete configuration files without
390 local changes during upgrades. The ``dpkg-maintscript-helper`` tool,
391 available from the dpkg package since *Wheezy*, can help with this.
394 The name of the files and directories installed by binary packages
395 must be encoded in UTF-8 and should be restricted to ASCII when
396 possible. In the system PATH, they must be restricted to ASCII.
399 Stop recommending to serve HTML documents from
400 ``/usr/share/doc/package``.
403 Packages distributing Info documents should use install-info's
404 trigger, and do not need anymore to depend on
405 ``dpkg (>= 1.15.4) | install-info``.
408 The ``escape`` capability is now documented.
411 ``mp3-decoder`` and ``mp3-encoder`` are removed.
416 Released August, 2012.
419 New *tasks* archive section.
422 ``build-arch`` and ``build-indep`` are now mandatory targets in
426 New section documenting the ``Vcs-*`` fields, which are already in
427 widespread use. Note the mechanism for specifying the Git branch
428 used for packaging in the Vcs-Git field.
431 The deprecated relations < and > now must not be used.
434 New ``Built-Using`` field, which must be used to document the source
435 packages for any binaries that are incorporated into this package at
436 build time. This is used to ensure that the archive meets license
437 requirements for providing source for all binaries.
440 Policy for dependencies between shared libraries and other packages
441 has been largely rewritten to document the ``symbols`` system and
442 more clearly document handling of shared library ABI changes.
443 ``symbols`` files are now recommended over ``shlibs`` files in most
444 situations. All maintainers of shared library packages should review
445 the entirety of this section.
448 Packages must not assume the ``/run`` directory exists or is usable
449 without a dependency on ``initscripts (>= 2.88dsf-13.3)`` until the
450 stable release of Debian supports ``/run``.
453 Packages including MIME configuration can now rely on triggers and
454 do not need to call update-mime.
457 New section documenting general requirements for alternate init
458 systems and specific requirements for integrating with upstart.
461 All copyright files must be encoded in UTF-8.
466 Released February, 2012.
469 New archive sections *education*, *introspection*, and
470 *metapackages* added.
473 The ``Architecture`` field in ``*.dsc`` files may now contain the
474 value ``any all`` for source packages building both
475 architecture-independent and architecture-dependent packages.
478 If a dependency is restricted to particular architectures, the list
479 of architectures must be non-empty.
482 ``/run`` is allowed as an exception to the FHS and replaces
483 ``/var/run``. ``/run/lock`` replaces ``/var/lock``. The FHS
484 requirements for the older directories apply to these directories as
485 well. Backward compatibility links will be maintained and packages
486 need not switch to referencing ``/run`` directly yet. Files in
487 ``/run`` should be stored in a temporary file system.
490 New section spelling out the requirements for packages that use
491 files in ``/run``, ``/var/run``, or ``/var/lock``. This generalizes
492 information previously only in 9.3.2.
495 Cron job file names must not contain ``.`` or ``+`` or they will be
496 ignored by cron. They should replace those characters with ``_``. If
497 a package provides multiple cron job files in the same directory,
498 they should each start with the package name (possibly modified as
499 above), ``-``, and then some suitable suffix.
502 Packages using doc-base do not need to call install-docs anymore.
505 Packages that declare the same ``conffile`` may see left-over
506 configuration files from each other even if they conflict.
509 The Policy rules around Motif libraries were just a special case of
510 normal rules for non-free dependencies and were largely obsolete, so
511 they have been removed.
514 ``debian/copyright`` is no longer required to list the Debian
515 maintainers involved in the creation of the package (although note
516 that the requirement to list copyright information is unchanged).
519 Version 1.0 of the "Machine-readable ``debian/copyright`` file"
520 specification is included.
523 This separate document has been retired and and its (short) contents
524 merged into Policy section 9.7. There are no changes to the
528 Packages may declare an interest in the perl-major-upgrade trigger
529 to be notified of major upgrades of perl.
532 ``ttf-japanese-{mincho, gothic}`` is renamed to
533 ``fonts-japanese-{mincho, gothic}``.
538 Released April, 2011.
541 Multiple clarifications throughout Policy where "installed" was used
542 and the more precise terms "unpacked" or "configured" were intended.
545 The maintainer address must accept mail from Debian role accounts
546 and the BTS. At least one human must be listed with their personal
547 email address in ``Uploaders`` if the maintainer is a shared email
548 address. The duties of a maintainer are also clearer.
551 All control fields are now classified as simple, folded, or
552 multiline, which governs whether their values must be a single line
553 or may be continued across multiple lines and whether line breaks
557 Parsers are allowed to accept paragraph separation lines containing
558 whitespace, but control files should use completely empty lines.
559 Ordering of paragraphs is significant. Field names must be composed
560 of printable ASCII characters except colon and must not begin with
564 The ``DM-Upload-Allowed`` field is now documented.
567 The system state maintainer scripts can rely upon during each
568 possible invocation is now documented. In several less-common cases,
569 this is stricter than Policy had previously documented. Packages
570 with complex maintainer scripts should be reviewed in light of this
574 The impact on system state when maintainer scripts that are part of
575 a circular dependency are run is now documented. Circular
576 dependencies are now a should not.
579 The system state when ``postinst`` and ``prerm`` scripts are run is
580 now documented, and the documentation of the special case of
581 dependency state for ``postrm`` scripts has been improved.
582 ``postrm`` scripts are required to gracefully skip actions if their
583 dependencies are not available.
586 GNU/Hurd systems are allowed ``/hurd`` and ``/servers`` directories
587 in the root filesystem.
590 Packages installing to architecture-specific subdirectories of
591 ``/usr/lib`` must use the value returned by
592 ``dpkg-architecture -qDEB_HOST_MULTIARCH``, not by
593 ``dpkg-architecture -qDEB_HOST_GNU_TYPE``; this is a path change on
594 i386 architectures and a no-op for other architectures.
597 ``mailx`` is now a virtual package provided by packages that install
598 ``/usr/bin/mailx`` and implement at least the POSIX-required
607 Date-based version components should be given as the four-digit
608 year, two-digit month, and then two-digit day, but may have embedded
612 Maintainer scripts must pass ``--package`` to ``dpkg-divert`` when
613 creating or removing diversions and must not use ``--local``.
616 Only ``dpkg-gencontrol`` supports variable substitution.
617 ``dpkg-genchanges`` (for ``*.changes``) and ``dpkg-source`` (for
621 Architecture restrictions and wildcards are also allowed in binary
622 package relationships provided that the binary package is not
623 architecture-independent.
626 ``Conflicts`` and ``Breaks`` should only be used when there are file
627 conflicts or one package breaks the other, not just because two
628 packages provide similar functionality but don't interfere.
631 The SONAME of a library should change whenever the ABI of the
632 library changes in a way that isn't backward-compatible. It should
633 not change if the library ABI changes are backward-compatible.
634 Discourage bundling shared libraries together in one package.
637 Ada Library Information (``*.ali``) files must be installed
641 Packages should normally not include a ``shlibs.local`` file since
642 we now have complete ``shlibs`` coverage.
645 The SONAME of a library may instead be of the form
646 ``name-major-version.so``.
649 Libtool ``.la`` files should not be installed for public libraries.
650 If they're required (for ``libltdl``, for instance), the
651 ``dependency_libs`` setting should be emptied. Library packages
652 historically including ``.la`` files must continue to include them
653 (with ``dependency_libs`` emptied) until all libraries that depend
654 on that library have removed or emptied their ``.la`` files.
657 Libraries no longer need to be built with ``-D_REENTRANT``, which
658 was an obsolete LinuxThreads requirement. Instead, say explicitly
659 that libraries should be built with threading support and to be
660 thread-safe if the library supports this.
663 ``/bin/sh`` scripts may assume that ``kill`` supports an argument of
664 ``-signal``, that ``kill`` and ``trap`` support the numeric signals
665 listed in the XSI extension, and that signal 13 (SIGPIPE) can be
666 trapped with ``trap``.
669 Use of ``/etc/logrotate.d/package`` for logrotate rules is now
673 Control information files should be owned by ``root:root`` and
674 either mode 644 or mode 755.
677 Packages providing alternatives for ``editor``, ``pager``,
678 ``x-terminal-emulator``, or ``x-window-manager`` should also provide
679 a slave alternative for the corresponding manual page.
682 Cgi-bin executable files may be installed in subdirectories of
683 ``/usr/lib/cgi-bin`` and web servers should serve out executables in
684 those subdirectories.
687 The GPL version 1 is now included in common-licenses and should be
688 referenced from there instead of included in the ``copyright`` file.
696 The required format for the date in a changelog entry and in the
697 Date control field is now precisely specified.
700 A control paragraph must not contain more than one instance of a
701 particular field name.
704 The ``Checksums-Sha1`` and ``Checksums-Sha256`` fields in ``*.dsc``
705 and ``*.changes`` files are now documented and recommended.
708 The ``Format`` field of ``.changes`` files is now 1.8. The
709 ``Format`` field syntax for source package ``.dsc`` files allows a
710 subtype in parentheses, and it is used for a different purpose than
711 the ``Format`` field for ``.changes`` files.
714 The syntax of the ``Maintainer`` field is now must rather than
718 The comma separating entries in ``Uploaders`` is now must rather
722 Architecture wildcards may be used in addition to specific
723 architectures in ``debian/control`` and ``*.dsc`` Architecture
724 fields, and in architecture restrictions in build relationships.
727 Maintainer scripts are no longer guaranteed to run with a
728 controlling terminal and must be able to fall back to noninteractive
729 behavior (debconf handles this). Maintainer scripts may abort if
730 there is no controlling terminal and no reasonable default for a
731 high-priority question, but should avoid this if possible.
734 ``Breaks`` should be used with ``Replaces`` for moving files between
738 ``Breaks`` should normally be used instead of ``Conflicts`` for
739 transient issues and moving files between packages. New
740 documentation of when each should be used.
743 Use ``Conflicts`` with ``Provides`` if only one provider of a
744 virtual facility can be installed at a time.
747 All shared library development files are no longer required to be in
748 the ``-dev`` package, only be available when the ``-dev`` package is
749 installed. This allows the ``-dev`` package to be split as long as
750 it depends on the additional packages.
753 The UID range of user accounts is extended to 1000-59999.
756 ``init.d`` scripts are a possible exception from the normal
757 requirement to use ``set -e`` in each shell script.
760 The UCB BSD license was removed from the list of licenses that
761 should be referenced from ``/usr/share/common-licenses/BSD``. It
762 should instead be included directly in ``debian/copyright``,
763 although it will still be in common-licenses for the time being.
766 ``SETTITLE`` is now documented (it has been supported for some
767 time). ``SETTITLE`` is like ``TITLE`` but takes a template instead
768 of a string to allow translation.
771 perl-base now provides perlapi-abiname instead of a package based
772 solely on the Perl version. Perl packages must now depend on
773 perlapi-$Config{debian\_abi}, falling back on ``$Config{version}``
774 if ``$Config{debian_abi}`` is not set.
777 Packages using ``Makefile.PL`` should use ``DESTDIR`` rather than
778 ``PREFIX`` to install into the package staging area. ``PREFIX`` only
779 worked due to a Debian-local patch.
784 Released January, 2010.
787 An FHS exception has been granted for multiarch libraries.
788 Permitting files to instead be installed to ``/lib/triplet`` and
789 ``/usr/lib/triplet`` directories.
792 Packages may not contain named pipes and should instead create them
793 in postinst and remove them in prerm or postrm.
796 ``/sys`` and ``/selinux`` directories are explicitly allowed as an
797 exception to the FHS.
802 Released August, 2009.
805 DEB\_\*\_ARCH\_CPU and DEB\_\*\_ARCH\_OS variables are now
806 documented and recommended over GNU-style variables for that
810 Source package Architecture fields may contain *all* in combination
811 with other architectures. Clarify when *all* and *any* may be used
812 in different versions of the field.
815 The Debian archive software does not support uploading to multiple
816 distributions with one ``*.changes`` file.
819 The Binary field may span multiple lines.
822 Shared library packages are no longer allowed to install libraries
823 in a non-standard location and modify ``ld.so.conf``. Packages
824 should either be installed in a standard library directory or
825 packages using them should be built with RPATH.
828 Installation directories for X programs have been clarified.
829 Packages are no longer required to pre-depend on x11-common before
830 installing into ``/usr/include/X11`` and ``/usr/lib/X11``.
833 Manual pages are no longer required to contain only characters
834 representable in the legacy encoding for that language.
837 Localized man pages should either be kept up-to-date with the
838 original version or warn that they're not up-to-date, either with
839 warning text or by showing missing or changed portions in the
843 install-info is now handled via triggers so packages no longer need
844 to invoke it in maintainer scripts. Info documents should now have
845 directory sections and entries in the document. Packages containing
846 info documents should add a dependency to support partial upgrades.
849 The requirement for Perl modules to have a versioned Depend and
850 Build-Depend on ``perl >= 5.6.0-16`` has been removed.
858 The list of archive sections has been significantly expanded. See
859 `this debian-devel-announce
860 message <http://lists.debian.org/debian-devel-announce/2009/03/msg00010.html>`__
861 for the list of new sections and rules for how to categorize
865 All packages must use debconf or equivalent for user prompting,
866 though essential packages or their dependencies may also fall back
870 The requirements for source package names are now explicitly spelled
874 Legacy XFree86 servers no longer get a special exception from the
875 FHS permitting ``/etc/X11/XF86Config-4``.
878 Removed obsolete dependency requirements for packages that use
882 Speedo fonts are now deprecated. The X backend was disabled starting
886 The GNU Free Documentation License version 1.3 is included in
887 common-licenses and should be referenced from there.
892 Released March, 2009.
895 Care should be taken when adding functionality to essential and such
896 additions create an obligation to support that functionality in
897 essential forever unless significant work is done.
900 Changelog files must be encoded in UTF-8.
903 Some format requirements for changelog files are now "must" instead
907 Alternative changelog formats have been removed. Debian only
908 supports one changelog format for the Debian Archive.
911 New nocheck option for DEB\_BUILD\_OPTIONS indicating any build-time
912 test suite provided by the package should not be run.
915 All control files must be encoded in UTF-8.
918 ``debian/control`` allows comment lines starting with # with no
919 preceding whitespace.
922 Init scripts ending in .sh are not handled specially. They are not
923 sourced and are not guaranteed to be run by ``/bin/sh`` regardless
924 of the #! line. This brings Policy in line with the long-standing
925 behavior of the init system in Debian.
928 The start action of an init script must exit successfully and not
929 start the daemon again if it's already running.
932 ``/var/run`` and ``/var/lock`` may be mounted as temporary
933 filesystems, and init scripts must therefore create any necessary
934 subdirectories dynamically.
937 ``/bin/sh`` scripts may assume that local can take multiple variable
938 arguments and supports assignment.
941 User mailboxes may be mode 600 and owned by the user rather than
942 mode 660, owned by user, and group mail.
950 The base section has been removed. contrib and non-free have been
951 removed from the section list; they are only categories. The base
952 system is now defined by priority.
955 If ``dpkg-source -x`` doesn't provide the source that will be
956 compiled, a debian/rules patch target is recommended and should do
957 whatever else is necessary.
960 Standardized the format of DEB\_BUILD\_OPTIONS. Specified permitted
961 characters for tags, required that tags be whitespace-separated,
962 allowed packages to assume non-conflicting tags, and required
963 unknown flags be ignored.
966 Added parallel=n to the standardized DEB\_BUILD\_OPTIONS tags,
967 indicating that a package should be built using up to n parallel
968 processes if the package supports it
971 Debian packages should not use convenience copies of code from other
972 packages unless the included package is explicitly intended to be
976 If dpkg-source -x doesn't produce source ready for editing and
977 building with dpkg-buildpackage, packages should include a
978 ``debian/README.source`` file explaining how to generate the patched
979 source, add a new modification, and remove an existing modification.
980 This file may also be used to document packaging a new upstream
981 release and any other complexity of the Debian build process.
984 The Uploaders field in debian/control may be wrapped.
987 An empty Debian revision is equivalent to a Debian revision of 0 in
991 New Homepage field for upstream web sites.
994 The Breaks field declares that this package breaks another and
995 prevents installation of the breaking package unless the package
996 named in Breaks is deconfigured first. This field should not be used
997 until the dpkg in Debian stable supports it.
1000 Clarify which files should go into a shared library package, into a
1001 separate package, or into the -dev package. Suggest -tools instead
1002 of -runtime for runtime support programs, since that naming is more
1006 Files in ``/etc/cron.{hourly,daily,weekly,monthly}`` must be
1007 configuration files (upgraded from should). Mention the hourly
1011 Packages providing ``/etc/X11/Xresources`` files need not conflict
1012 with ``xbase (<< 3.3.2.3a-2)``, which is long-obsolete.
1015 Manual pages in locale-specific directories should use either the
1016 legacy encoding for that directory or UTF-8. Country names should
1017 not be included in locale-specific manual page directories unless
1018 indicating a significant difference in the language. All characters
1019 in the manual page source should be representable in the legacy
1020 encoding for a locale even if the man page is encoded in UTF-8.
1023 The Apache 2.0 license is now in common-licenses and should be
1024 referenced rather than quoted in ``debian/copyright``.
1027 Packages in contrib and non-free should state in the copyright file
1028 that the package is not part of Debian GNU/Linux and briefly explain
1032 Underscore (``_``) is allowed in debconf template names.
1037 Released December, 2007.
1040 Package version numbers may contain tildes, which sort before
1041 anything, even the end of a part.
1044 Scripts may assume that ``/bin/sh`` supports local (at a basic
1045 level) and that its test builtin (if any) supports -a and -o binary
1049 The substitution variable ${binary:Version} should be used in place
1050 of ${Source-Version} for dependencies between packages of the same
1054 Substantial reorganization and renaming of sections in the Debian
1055 menu structure. Packages with menu entries should be reviewed to see
1056 if the menu section has been renamed or if one of the new sections
1057 would be more appropriate.
1060 The Source field in a .changes file may contain a version number in
1064 The acceptable values for the Urgency field are low, medium, high,
1065 critical, or emergency.
1068 The shlibs file now allows an optional type field, indicating the
1069 type of package for which the line is valid. The only currently
1070 supported type is udeb, used with packages for the Debian Installer.
1073 Packages following the Debian Configuration management specification
1074 must allow for translation of their messages by using a
1075 gettext-based system such as po-debconf.
1078 GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should be
1079 referenced rather than quoted in debian/copyright.
1084 Released October, 2006.
1086 This release broke the normal rule against introducing normative changes
1087 without changing the major patch level.
1090 Maintainer scripts must not be world writeable (up from a should to
1096 Released April, 2006.
1099 Revert the cgi-lib change.
1104 Released April, 2006.
1107 It is now possible to create shared libraries without relocatable
1108 code (using -fPIC) in certain exceptional cases, provided some
1109 procedures are followed, and for creating static libraries with
1110 relocatable code (again, using -fPIC). Discussion on
1111 debian-devel@lists.debian.org, getting a rough consensus, and
1112 documenting it in README.Debian constitute most of the process.
1115 Packages should install any relevant files into the directories
1116 ``/usr/include/X11/`` and ``/usr/lib/X11/``, but if they do so, they
1117 must pre-depend on ``x11-common (>= 1:7.0.0)``
1122 Released April, 2006.
1125 Packages shipping web server CGI files are expected to install them
1126 in ``/usr/lib/cgi-lib/`` directories. This location change perhaps
1127 should be documented in NEWS
1130 Web server packages should include a standard scriptAlias of cgi-lib
1131 to ``/usr/lib/cgi-lib``.
1134 The version of FHS mandated by policy has been upped to 2.3. There
1135 should be no changes required for most packages, though new top
1136 level directories ``/media``, ``/srv``, etc. may be of interest.
1139 All fields, apart from the Uploaders field, in the control file are
1140 supposed to be a single logical line, which may be spread over
1141 multiple physical lines (newline followed by space is elided).
1142 However, any parser for the control file must allow the Uploaders
1143 field to be spread over multiple physical lines as well, to prepare
1147 When scripts are installed into a directory in the system PATH, the
1148 script name should not include an extension that denotes the
1149 scripting language currently used to implement it.
1152 packages that invoke initscripts now must use invoke-rc.d to do so
1153 since it also pays attention to run levels and other local
1156 11.8.5.2, 11.8.7, etc
1157 We no longer use ``/usr/X11R6``, since we have migrated away to
1158 using Xorg paths. This means, for one thing, fonts live in
1159 ``/usr/share/fonts/X11/`` now, and ``/usr/X11R6`` is gone.
1164 Released June, 2005.
1166 Recommend doc-base, and not menu, for registering package
1170 Run time support programs should live in subdirectories of
1171 ``/usr/lib/`` or ``/usr/share``, and preferably the shared lib is
1172 named the same as the package name (to avoid name collisions).
1175 It is recommended that HTTP servers provide an alias /images to
1176 allow packages to share image files with the web server
1181 Released August, 2003.
1184 Prompting the user should be done using debconf. Non debconf user
1185 prompts are now deprecated.
1190 Released July, 2003.
1192 Restructuring caused shifts in section numbers and bumping of the
1193 minor version number.
1195 Many packaging manual appendices that were integrated into policy
1196 sections are now empty, and replaced with links to the Policy. In
1197 particular, the appendices that included the list of control fields
1198 were updated (new fields like Closes, Changed-By were added) and the
1199 list of fields for each of control, .changes and .dsc files is now
1200 in Policy, and they're marked mandatory, recommended or optional
1201 based on the current practice and the behavior of the deb-building
1204 Elimination of needlessly deep section levels, primarily in the
1205 chapter Debian Archive, from which two new chapters were split out,
1206 Binary packages and Source packages. What remained was reordered
1207 properly, that is, some sects became sects etc.
1209 Several sections that were redundant, crufty or simply not designed
1210 with any sort of vision, were rearranged according to the formula
1211 that everything should be either in the same place or properly
1212 interlinked. Some things remained split up between different
1213 chapters when they talked about different aspects of files: their
1214 content, their syntax, and their placement in the file system. In
1215 particular, see the new sections about changelog files.
1218 Added Games/Simulation and Apps/Education to menu sub-policy
1221 Debian changelogs should be UTF-8 encoded.
1224 shared libraries must be linked against all libraries that they use
1225 symbols from in the same way that binaries are.
1228 build-depends-indep need not be satisfied during clean target.
1236 packages providing the x-terminal-emulator virtual package ought to
1237 ensure that they interpret the command line exactly like xterm does.
1240 Window managers compliant with the Window Manager Specification
1241 Project may add 40 points for ranking in the alternatives
1246 Released March, 2003.
1249 The section describing the Description: package field once again has
1250 full details of the long description format.
1253 Clarified that if a package has non-build-essential
1254 build-dependencies, it should have them listed in the Build-Depends
1255 and related fields (i.e. it's not merely optional).
1258 When asked to restart a service that isn't already running, the init
1259 script should start the service.
1262 If the purpose of a package is to provide examples, then the example
1263 files can be installed into ``/usr/share/doc/package`` (rather than
1264 ``/usr/share/doc/package/examples``).
1269 Released November, 2002.
1272 It is no longer necessary to keep a log of changes to the upstream
1273 sources in the copyright file. Instead, all such changes should be
1274 documented in the changelog file.
1277 Build-Depends, Build-Conflicts, Build-Depends-Indep, and
1278 Build-Conflicts-Indep must also be satisfied when the clean target
1282 A new Apps/Science menu section is available
1285 debconf specification cleared up, various changes.
1288 It is no longer recommended to create symlinks from nonexistent
1289 manual pages to undocumented(7). Missing manual pages for programs
1295 Released August, 2002.
1297 Packages no longer have to ask permission to call MAKEDEV in
1298 postinst, merely notifying the user ought to be enough.
1301 cryptographic software may now be included in the main archive.
1304 task packages are no longer permitted; tasks are now created by a
1305 special Tasks: field in the control file.
1308 window managers that support netwm can now add 20 points when they
1309 add themselves as an alternative for ``/usr/bin/x-window-manager``
1312 The default compilation options have now changed, one should provide
1313 debugging symbols in all cases, and optionally step back
1314 optimization to -O0, depending on the DEB\_BUILD\_OPTIONS
1315 environment variable.
1318 Added mention of build-arch, build-indep, etc, in describing the
1319 relationships with Build-Depends, Build-Conflicts,
1320 Build-Depends-Indep, and Build-Conflicts-Indep. May need to
1321 review the new rules.
1324 Changed rules on how, and when, to invoke ldconfig in maintainer
1325 scripts. Long rationale.
1327 *Added the last note in 3.5.6 upgrading checklist item regarding build
1328 rules, please see below*
1333 Released July, 2001.
1336 Emacs and TeX are no longer mandated by policy to be priority
1340 Programs that access docs need to do so via ``/usr/share/doc``, and
1341 not via ``/usr/doc/`` as was the policy previously
1344 Putting documentation in ``/usr/doc`` versus ``/usr/share/doc`` is
1345 now a "serious" policy violation.
1348 For web servers, one should not provide non-local access to the
1349 ``/usr/share/doc`` hierarchy. If one can't provide access controls
1350 for the http://localhost/doc/ directory, then it is preferred that
1351 one ask permission to expose that information during the install.
1354 There are new rules for build-indep/build-arch targets and there is
1355 a new Build-Depend-Indep semantic.
1363 Manpages should not rely on header information to have alternative
1364 manpage names available; it should only use symlinks or .so pages to
1367 *Clarified note in 3.5.3.0 upgrading checklist regarding examples
1368 and templates: this refers only to those examples used by scripts;
1369 see section 10.7.3 for the whole story*
1371 Included a new section 10.9.1 describing the use of
1372 dpkg-statoverride; this does not have the weight of policy
1374 Clarify Standards-Version: you don't need to rebuild your packages
1375 just to change the Standards-Version!
1378 Plugins are no longer bound by all the rules of shared libraries
1380 X Windows related things:
1382 Clarification of priority levels of X Window System related
1386 Rules for defining x-terminal-emulator improved
1389 X Font policy rewritten: you must read this if you provide fonts
1390 for the X Window System
1393 Packages must not ship ``/usr/X11R6/lib/X11/app-defaults/``
1396 X-related packages should usually use the regular FHS locations;
1397 imake-using packages are exempted from this
1400 OpenMotif linked binaries have the same rules as
1401 OSF/Motif-linked ones
1406 Released April, 2001.
1409 The system-wide mail directory is now /var/mail, no longer
1410 /var/spool/mail. Any packages accessing the mail spool should access
1411 it via /var/mail and include a suitable Depends field;
1414 The perl policy is now part of Debian policy proper. Perl programs
1415 and modules should follow the current Perl policy
1420 Released April, 2001.
1423 Build-Depends arch syntax has been changed to be less ambiguous.
1424 This should not affect any current packages
1427 Examples and templates files for use by scripts should now live in
1428 ``/usr/share/<package>`` or ``/usr/lib/<package>``, with symbolic
1429 links from ``/usr/share/doc/<package>/examples`` as needed
1434 Released February, 2001.
1437 X app-defaults directory has moved from
1438 ``/usr/X11R6/lib/X11/app-defaults`` to ``/etc/X11/app-defaults``
1443 Released February, 2001.
1446 dpkg-shlibdeps now uses objdump, so shared libraries have to be run
1447 through dpkg-shlibdeps as well as executables
1452 Released January, 2001.
1455 Font packages for the X Window System must now declare a dependency
1456 on ``xutils (>= 4.0.2)``
1461 Released January, 2001.
1463 This release broke the normal rule against introducing normative changes
1464 without changing the major patch level.
1467 Daemon startup scripts in ``/etc/init.d/`` should not contain
1468 modifiable parameters; these should be moved to a file in
1472 Files in ``/usr/share/doc`` must not be referenced by any program.
1473 If such files are needed, they must be placed in
1474 ``/usr/share/<package>/``, and symbolic links created as required in
1475 ``/usr/share/doc/<package>/``
1477 Much of the packaging manual has now been imported into the policy
1483 Released August, 2000.
1486 A package of priority standard or higher may provide two binaries,
1487 one compiled with support for the X Window System, and the other
1493 Released August, 2000.
1496 By default executables should not be built with the debugging option
1497 -g. Instead, it is recommended to support building the package with
1498 debugging information optionally.
1501 Policy for packages where the upstream uses HTML changelog files has
1502 been expanded. In short, a plain text changelog file should always
1503 be generated for the upstream changes
1505 Please note that the new release of the X window system (3.2) shall
1506 probably need sweeping changes in policy
1508 Policy for packages providing the following X-based features has
1512 X server (virtual package xserver)
1515 X terminal emulator (virtual package x-terminal-emulator)
1518 X window manager (virtual package x-window-manager, and
1519 ``/usr/bin/x-window-manager`` alternative, with priority
1520 calculation guidelines)
1523 X fonts (this section has been written from scratch)
1526 X application defaults
1529 Policy for packages using the X Window System and FHS issues has
1533 No package may contain or make hard links to conffiles
1536 Noted that newer dpkg versions do not require extreme care in always
1537 creating the shared lib before the symlink, so the unpack order be
1543 Released November, 1999.
1546 Correction to semantics of architecture lists in Build-Depends etc.
1547 Should not affect many packages
1552 Released October, 1999.
1555 ``/usr/doc/<package>`` has to be a symlink pointing to
1556 ``/usr/share/doc/<package>``, to be maintained by postinst and prerm
1560 Introduced source dependencies (Build-Depends, etc.)
1563 ``/etc/rc.boot`` has been deprecated in favour of ``/etc/rcS.d``.
1564 (Packages should not be touching this directory, but should use
1565 update-rc.d instead)
1568 update-rc.d is now the *only* allowable way of accessing the
1569 ``/etc/rc?.d/[SK]??*`` links. Any scripts which manipulate them
1570 directly must be changed to use update-rc.d instead. (This is
1571 because the file-rc package handles this information in an
1575 Architecture-specific examples go in ``/usr/lib/<package>/examples``
1576 with symlinks from ``/usr/share/doc/<package>/examples/*`` or from
1577 ``/usr/share/doc/<package>/examples`` itself
1580 Updated FHS to a 2.1 draft; this reverts ``/var/state`` to
1584 Added MIME sub-policy document
1587 VISUAL is allowed as a (higher priority) alternative to EDITOR
1590 Modified liblockfile description, which affects mailbox-accessing
1591 programs. Please see the policy document for details
1594 If a package provides a changelog in HTML format, a text-only
1595 version should also be included. (Such a version may be prepared
1596 using ``lynx -dump -nolist``.)
1599 Description of how to handle version numbers based on dates added
1604 Released July, 1999.
1607 Added the clarification that the .la files are essential for the
1608 packages using libtool's libltdl library, in which case the .la
1609 files must go in the run-time library package
1614 Released June, 1999.
1617 Debian formally moves from the FSSTND to the FHS. This is a major
1618 change, and the implications of this move are probably not all
1622 Only 3 digits of the Standards version need be included in control
1623 files, though all four digits are still permitted.
1626 The location of the GPL has changed to
1627 ``/usr/share/common-licenses``. This may require changing the
1628 copyright files to point to the correct location of the GPL and
1629 other major licenses
1632 Packages that use libtool to create shared libraries must include
1633 the .la files in the -dev packages
1636 Use logrotate to rotate log files
1639 section 5.8 has been rewritten (Programs for the X Window System)
1642 There is now an associated menu policy, in a separate document, that
1643 carries the full weight of Debian policy
1646 Programs which need to modify the files ``/var/run/utmp``,
1647 ``/var/log/wtmp`` and ``/var/log/lastlog`` must be installed setgid
1653 Released October, 1998.
1655 *Please note that section numbers below this point may not match the
1656 current Policy Manual.*
1658 - Rearranged the manual to create a new Section 4, Files
1660 - Section 3.3 ("Files") was moved to Section 4. The Sections that
1661 were Section 4 and Section 5 were moved down to become Section 5
1664 - What was Section 5.5 ("Log files") is now a subsection of the new
1665 Section 4 ("Files"), becoming section 4.8, placed after
1666 "Configuration files", moving the Section 4.8 ("Permissions and
1667 owners") to Section 4.9. All subsections of the old Section 5
1668 after 5.5 were moved down to fill in the number gap.
1670 - Modified the section about changelog files to accommodate upstream
1671 changelogs which were formatted as HTML. These upstream changelog
1672 files should now be accessible as
1673 ``/usr/doc/package/changelog.html.gz``
1675 - Symlinks are permissible to link the real, or upstream, changelog
1676 name to the Debian mandated name.
1678 - Clarified that HTML documentation should be present in some package,
1679 though not necessarily the main binary package.
1681 - Corrected all references to the location of the copyright files. The
1682 correct location is ``/usr/doc/package/copyright``
1684 - Ratified the architecture specification strings to cater to the HURD.
1689 Released April, 1998.
1691 Updated section 3.3.5 Symbolic links
1692 symbolic links within a toplevel directory should be relative,
1693 symbolic links between toplevel directories should be absolute (cf.,
1694 Policy Weekly Issue#6, topic 2)
1696 Updated section 4.9 Games
1697 manpages for games should be installed in ``/usr/man/man6`` (cf.,
1698 Policy Weekly Issue#6, topic 3)
1700 Updated Chapter 12 Shared Libraries
1701 ldconfig must be called in the postinst script if the package
1702 installs shared libraries (cf., Policy Weekly Issue #6,
1708 Released January, 1998
1710 Updated section 3.3.4 Scripts
1711 - /bin/sh may be any POSIX compatible shell
1713 - scripts including bashisms have to specify ``/bin/bash`` as
1716 - scripts which create files in world-writable directories (e.g.,
1717 in ``/tmp``) should use tempfile or mktemp for creating the
1720 Updated section 3.3.5 Symbolic Links
1721 symbolic links referencing compressed files must have the same file
1722 extension as the referenced file
1724 Updated section 3.3.6 Device files
1725 ``/dev/tty*`` serial devices should be used instead of ``/dev/cu*``
1727 Updated section 3.4.2 Writing the scripts in ``/etc/init.d``
1728 - all ``/etc/init.d`` scripts have to provide the following
1729 options: start, stop, restart, force-reload
1731 - the reload option is optional and must never stop and restart the
1734 Updated section 3.5 Cron jobs
1735 cron jobs that need to be executed more often than daily should be
1736 installed into ``/etc/cron.d``
1738 Updated section 3.7 Menus
1739 removed section about how to register HTML docs to \`menu' (the
1740 corresponding section in 4.4, Web servers and applications, has been
1741 removed in policy 2.2.0.0 already, so this one was obsolete)
1743 New section 3.8 Keyboard configuration
1744 details about how the backspace and delete keys should be handled
1746 New section 3.9 Environment variables
1747 no program must depend on environment variables to get a reasonable
1748 default configuration
1750 New section 4.6 News system configuration
1751 ``/etc/news/organization`` and ``/etc/news/server`` should be
1752 supported by all news servers and clients
1754 Updated section 4.7 Programs for the X Window System
1755 - programs requiring a non-free Motif library should be provided as
1756 foo-smotif and foo-dmotif package
1758 - if lesstif works reliably for such program, it should be linked
1759 against lesstif and not against a non-free Motif library
1761 Updated section 4.9 Games
1762 games for X Windows have to be installed in ``/usr/games``, just as
1768 Released September, 1997.
1770 - new section \`4.2 Daemons' including rules for ``/etc/services``,
1771 ``/etc/protocols``, ``/etc/rpc``, and ``/etc/inetd.conf``
1773 - updated section about \`Configuration files': packages may not touch
1774 other packages' configuration files
1776 - MUAs and MTAs have to use liblockfile
1781 Released July, 1997.
1783 - added section 4.1 \`Architecture specification strings': use
1784 <arch>-linux where <arch> is one of the following: i386, alpha, arm,
1785 m68k, powerpc, sparc.
1787 - detailed rules for ``/usr/local``
1791 - editor/pager policy
1797 - don't install shared libraries as executable
1799 - app-defaults files may not be conffiles
1804 Released March, 1997.
1806 - two programs with different functionality must not have the same name
1810 - "Standard for Console Messages"
1812 - Libraries should be compiled with ``-D_REENTRANT``
1814 - Libraries should be stripped with ``strip --strip-unneeded``
1819 Released November, 1996.
1821 - Some changes WRT shared libraries
1826 Released September, 1996.
1828 - No hard links in source packages
1830 - Do not use ``dpkg-divert`` or ``update-alternatives`` without
1833 - Shared libraries must be installed stripped
1838 Released August, 1996.
1840 - Upstream changelog must be installed too