Informally, the criteria used for inclusion is that the material meet one of the following requirements:
The material presented represents an interface to the packaging system that is mandated for use, and is used by, a significant number of packages, and therefore should not be changed without peer review. Package maintainers can then rely on this interface not changing, and the package management software authors need to ensure compatibility with this interface definition. (Control file and changelog file formats are examples.)
If there are a number of technically viable choices that can be made, but one needs to select one of these options for inter-operability. The version number format is one example.
Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces.
Compare RFC 2119. Note, however, that these words are used in a different way in this document.
The Debian archive software uses the term "component" internally and in the Release file format to refer to the division of an archive. The Debian Social Contract simply refers to "areas." This document uses terminology similar to the Social Contract.
See What Does Free
Mean? for more about what we mean by free software.
It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis.
This is an important criterion because we are trying to produce, amongst other things, a free Unix.
A sample implementation of such a whitelist written for the Mailman mailing list management software is used for mailing lists hosted by alioth.debian.org.
The detailed procedure for gracefully orphaning a package can be found in the Debian Developer's Reference (see Related documents, Section 1.4).
The blurb that comes with a program in its announcements and/or
README files is rarely suitable for use in a description. It is
usually aimed at people who are already in the community where the package is
used.
Essential is needed in part to avoid unresolvable dependency loops on upgrade. If packages add unnecessary dependencies on packages in this set, the chances that there will be an unresolvable dependency loop caused by forcing these Essential packages to be configured first before they need to be is greatly increased. It also increases the chances that frontends will be unable to calculate an upgrade path, even if one exists.
Also, functionality is rarely ever removed from the Essential set, but packages have been removed from the Essential set when the functionality moved to a different package. So depending on these packages just in case they stop being essential does way more harm than good.
Debconf or another tool that implements the Debian Configuration
Management Specification will also be installed, and any versioned dependencies
on it will be satisfied before preconfiguration begins.
See the file upgrading-checklist for information about policy
which has changed between different versions of this document.
Rationale:
This allows maintaining the list separately from the policy documents (the list does not need the kind of control that the policy documents do).
Having a separate package allows one to install the build-essential packages on a machine, as well as allowing other packages such as tasks to require installation of the build-essential packages using the depends relation.
The separate package allows bug reports against the list to be categorized separately from the policy management process in the BTS.
The reason for this is that dependencies change, and you should list all those
packages, and only those packages that you need directly.
What others need is their business. For example, if you only link against
libimlib, you will need to build-depend on
libimlib2-dev but not against any libjpeg* packages,
even though libimlib2-dev currently depends on them: installation
of libimlib2-dev will automatically ensure that all of its
run-time dependencies are satisfied.
Mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries.
Although there is nothing stopping an author who is also the Debian maintainer from using this changelog for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people. In such a case, however, it might be better to maintain the package as a non-native package.
To be precise, the string should match the following Perl regular expression:
/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
Then all of the bug numbers listed will be closed by the archive maintenance
software (dak) using the version of the changelog
entry.
In the case of a sponsored upload, the uploader signs the files, but the changelog maintainer name and address are those of the person who prepared this release. If the preparer of the release is not one of the usual maintainers of the package (as listed in the Maintainer or Uploaders control fields of the package), the first line of the changelog is conventionally used to explain why a non-maintainer is uploading the package. The Debian Developer's Reference (see Related documents, Section 1.4) documents the conventions used.
This is the same as the format generated by date -R.
The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved.
This is not currently detected when building source packages, but only when extracting them.
Hard links may be permitted at some point in the future, but would require a fair amount of work.
Setgid directories are allowed.
Another common way to do this is for build to depend on
build-stamp and to do nothing else, and for the
build-stamp target to do the building and to touch
build-stamp on completion. This is especially useful if the build
routine creates a file or directory called build; in such a case,
build will need to be listed as a phony target (i.e., as a
dependency of the .PHONY target). See the documentation of
make for more information on phony targets.
This split allows binary-only builds to not install the dependencies required for the build-indep target and skip any resource-intensive build tasks that are only required when building architecture-independent binary packages.
The fakeroot package often allows one to build a package correctly
even without being root.
Some packages support any delimiter, but whitespace is the easiest to parse inside a makefile and avoids ambiguity with flag values that contain commas.
Packages built with make can often implement this by passing the -jn option to make.
files.new is used as a temporary file by
dpkg-gencontrol and dpkg-distaddfile - they write a
new version of files here before renaming it, to avoid leaving a
corrupted copy if an error occurs.
For example, parts of the GNU build system work like this.
Having multiple copies of the same code in Debian is inefficient, often creates either static linking or shared library conflicts, and, most importantly, increases the difficulty of handling security vulnerabilities in the duplicated code.
dpkg's internal databases are in a similar format.
The paragraphs are also sometimes referred to as stanzas.
This folding method is similar to RFC 5322, allowing control files that contain only one paragraph and no multiline fields to be read by parsers written for RFC 5322.
It is customary to leave a space after the package name if a version number is specified.
In the past, people specified the full version number in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be specified, in this example "2.3.0". All four components may still be used if someone wishes to do so.
Alphanumerics are A-Za-z0-9 only.
One common use of ~ is for upstream pre-releases. For example, 1.0~beta1~svn1245 sorts earlier than 1.0~beta1, which sorts earlier than 1.0.
The author of this manual has heard of a package whose versions went 1.1, 1.2, 1.3, 1, 2.1, 2.2, 2 and so forth.
Completely empty lines will not be rendered as blank lines. Instead, they will cause the parser to think you're starting a whole new record in the control file, and will therefore likely abort with an error.
Example distribution names in the Debian archive used in .changes
files are:
This distribution value refers to the developmental part of the Debian distribution tree. Most new packages, new upstream versions of packages and bug fixes go into the unstable directory tree.
The packages with this distribution value are deemed by their maintainers to be high risk. Oftentimes they represent early beta or developmental packages from various sources that the maintainers want people to try, but are not ready to be a part of the other parts of the Debian distribution tree.
Others are used for updating stable releases or for security uploads. More information is available in the Debian Developer's Reference, section "The Debian archive".
The source formats currently supported by the Debian archive software are 1.0, 3.0 (native), and 3.0 (quilt).
Other urgency values are supported with configuration changes in the archive software but are not used in Debian. The urgency affects how quickly a package will be considered for inclusion into the testing distribution and gives an indication of the importance of any fixes included in the upload. Emergency and critical are treated as synonymous.
A space after each comma is conventional.
That is, the parts which are not the .dsc.
This is so that if an error occurs, the user interrupts dpkg or
some other unforeseen circumstance happens you don't leave the user with a
badly-broken package when dpkg attempts to repeat the action.
This can happen if the new version of the package no longer pre-depends on a package that had been partially upgraded.
For example, suppose packages foo and bar are "Installed" with foo
depending on bar. If an upgrade of bar were started and then aborted, and then
an attempt to remove foo failed because its prerm script failed,
foo's postinst abort-remove would be called with bar only
"Half-Installed".
This is often done by checking whether the command or facility the
postrm intends to call is available before calling it. For
example:
if [ "$1" = purge ] && [ -e /usr/share/debconf/confmodule ]; then
. /usr/share/debconf/confmodule
db_purge
fi
in postrm purges the debconf configuration for the
package if debconf is installed.
Part of the problem is due to what is arguably a bug in dpkg.
Historical note: Truly ancient (pre-1997) versions of dpkg passed
<unknown> (including the angle brackets) in this case. Even
older ones did not pass a second argument at all, under any circumstance. Note
that upgrades using such an old dpkg version are unlikely to work for other
reasons, even if this old argument behavior is handled by your postinst script.
This approach makes dependency resolution easier. If two packages A and B are being upgraded, the installed package A depends on exactly the installed package B, and the new package A depends on exactly the new package B (a common situation when upgrading shared libraries and their corresponding development packages), satisfying the dependencies at every stage of the upgrade would be impossible. This relaxed restriction means that both new packages can be unpacked together and then configured in their dependency order.
It is possible that a future release of dpkg may add the ability
to specify a version number for each virtual package it provides. This feature
is not yet present, however, and is expected to be used only infrequently.
To see why Breaks is normally needed in addition to
Replaces, consider the case of a file in the package
foo being taken over by the package foo-data.
Replaces will allow foo-data to be installed and take
over that file. However, without Breaks, nothing requires
foo to be upgraded to a newer version that knows it does not
include that file and instead depends on foo-data. Nothing would
prevent the new foo-data package from being installed and then
removed, removing the file that it took over from foo. After that
operation, the package manager would think the system was in a consistent
state, but the foo package would be missing one of its files.
Replaces is a one way relationship. You have to install the replacing package after the replaced package.
There is no Build-Depends-Arch; this role is essentially met with Build-Depends. Anyone building the build-indep and binary-indep targets is assumed to be building the whole package, and therefore installation of all build dependencies is required.
The autobuilders use dpkg-buildpackage -B, which calls build, not build-arch since it does not yet know how to check for its existence, and binary-arch. The purpose of the original split between Build-Depends and Build-Depends-Indep was so that the autobuilders wouldn't need to install extra packages needed only for the binary-indep targets. But without a build-arch/build-indep split, this didn't work, since most of the work is done in the build target, not in the binary target.
Build-Depends in the source package is not adequate since it (rightfully) does not document the exact version used in the build.
The archive software might reject packages that refer to non-existent sources.
This is a convention of shared library versioning, but not a requirement. Some libraries use the SONAME as the full library file name instead and therefore do not need a symlink. Most, however, encode additional information about backwards-compatible revisions as a minor version number in the file name. The SONAME itself only changes when binaries linked with the earlier version of the shared library may no longer work, but the filename may change with each release of the library. See Run-time shared libraries, Section 8.1 for more information.
The package management system requires the library to be placed before the
symbolic link pointing to it in the .deb file. This is so that
when dpkg comes to install the symlink (overwriting the previous
symlink pointing at an older version of the library), the new shared library is
already in place. In the past, this was achieved by creating the library in
the temporary packaging directory before creating the symlink. Unfortunately,
this was not always effective, since the building of the tar file in the
.deb depended on the behavior of the underlying file system. Some
file systems (such as reiserfs) reorder the files so that the order of creation
is forgotten. Since version 1.7.0, dpkg reorders the files itself
as necessary when building a package. Thus it is no longer important to
concern oneself with the order of file creation.
These are currently /usr/local/lib plus directories under
/lib and /usr/lib matching the multiarch triplet for
the system architecture.
During install or upgrade, the preinst is called before the new files are unpacked, so calling "ldconfig" is pointless. The preinst of an existing package can also be called if an upgrade fails. However, this happens during the critical time when a shared libs may exist on-disk under a temporary name. Thus, it is dangerous and forbidden by current policy to call "ldconfig" at this time.
When a package is installed or upgraded, "postinst configure" runs after the new files are safely on-disk. Since it is perfectly safe to invoke ldconfig unconditionally in a postinst, it is OK for a package to simply put ldconfig in its postinst without checking the argument. The postinst can also be called to recover from a failed upgrade. This happens before any new files are unpacked, so there is no reason to call "ldconfig" at this point.
For a package that is being removed, prerm is called with all the files intact, so calling ldconfig is useless. The other calls to "prerm" happen in the case of upgrade at a time when all the files of the old package are on-disk, so again calling "ldconfig" is pointless.
postrm, on the other hand, is called with the "remove" argument just after the files are removed, so this is the proper time to call "ldconfig" to notify the system of the fact that the shared libraries from the package are removed. The postrm can be called at several other times. At the time of "postrm purge", "postrm abort-install", or "postrm abort-upgrade", calling "ldconfig" is useless because the shared lib files are not on-disk. However, when "postrm" is invoked with arguments "upgrade", "failed-upgrade", or "disappear", a shared lib may exist on-disk under a temporary filename.
For example, a package-name-config script or
pkg-config configuration files.
This wording allows the development files to be split into several packages,
such as a separate architecture-independent
libraryname-headers, provided that the development
package depends on all the required additional packages.
Previously, ${Source-Version} was used, but its name was confusing and it has been deprecated since dpkg 1.13.19.
A shlibs file represents an SONAME as a library name and version
number, such as libfoo VERSION, instead of recording the actual
SONAME. If the SONAME doesn't match one of the two expected formats
(libfoo-VERSION.so or libfoo.so.VERSION), it cannot
be represented.
dpkg-shlibdeps will use a program like objdump or
readelf to find the libraries and the symbols in those libraries
directly needed by the binaries or shared libraries in the package.
The easiest way to call dpkg-shlibdeps correctly is to use a
package helper framework such as debhelper. If you are using
debhelper, the dh_shlibdeps program will do this work
for you. It will also correctly handle multi-binary packages.
dh_shlibdeps from the debhelper suite will
automatically add this option if it knows it is processing a udeb.
Again, dh_shlibdeps and dh_gencontrol will handle
everything except the addition of the variable to the control file for you if
you're using debhelper, including generating separate
substvars files for each binary package and calling
dpkg-gencontrol with the appropriate flags.
A good example of where this helps is the following. We could update
libimlib with a new version that supports a new revision of a
graphics format called dgf (but retaining the same major version number) and
depends on a new library package libdgf4 instead of the older
libdgf3. If we used ldd to add dependencies for
every library directly or indirectly linked with a binary, every package that
uses libimlib would need to be recompiled so it would also depend
on libdgf4 in order to retire the older libdgf3
package. Since dependencies are only added based on ELF NEEDED
attribute, packages using libimlib can rely on
libimlib itself having the dependency on an appropriate version of
libdgf and do not need rebuilding.
An example of an "unreasonable" program is one that uses library interfaces that are documented as internal and unsupported. If the only programs or libraries affected by a change are "unreasonable" ones, other techniques, such as declaring Breaks relationships with affected packages or treating their usage of the library as bugs in those packages, may be appropriate instead of changing the SONAME. However, the default approach is to change the SONAME for any change to the ABI that could break a program.
An example may clarify. Suppose the source package foo generates
two binary packages, libfoo2 and foo-runtime. When
building the binary packages, the contents of the packages are staged in the
directories debian/libfoo2 and debian/foo-runtime
respectively. (debian/tmp could be used instead of one of these.)
Since libfoo2 provides the libfoo shared library, it
will contain a symbols file, which will be installed in
debian/libfoo2/DEBIAN/symbols, eventually to be included as a
control file in that package. When dpkg-shlibdeps is run on the
executable debian/foo-runtime/usr/bin/foo-prog, it will examine
the debian/libfoo2/DEBIAN/symbols file to determine whether
foo-prog's library dependencies are satisfied by any of the
libraries provided by libfoo2. Since those binaries were linked
against the just-built shared library as part of the build process, the
symbols file for the newly-built libfoo2 must take
precedence over a symbols file for any other libfoo2
package already installed on the system.
This can be determined by using the command
readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME
An example of where this may be needed is with a library that implements the
libGL interface. All GL implementations provide the same set of base
interfaces, and then may provide some additional interfaces only used by
programs that require that specific GL implementation. So, for example,
libgl1-mesa-glx may use the following symbols file:
libGL.so.1 libgl1
| libgl1-mesa-glx #MINVER#
publicGlSymbol@Base 6.3-1
[...]
implementationSpecificSymbol@Base 6.5.2-7 1
[...]
Binaries or shared libraries using only publicGlSymbol would depend only on libgl1 (which may be provided by multiple packages), but ones using implementationSpecificSymbol would get a dependency on libgl1-mesa-glx (>= 6.5.2-7)
This field should normally not be necessary, since if the behavior of any symbol has changed, the corresponding symbol minimal-version should have been increased. But including it makes the symbols system more robust by tightening the dependency in cases where the package using the shared library specifically requires at least a particular version of the shared library development package for some reason.
If you are using debhelper, dh_makeshlibs will take
care of calling either dpkg-gensymbols or generating a
shlibs file as appropriate.
This is what dh_makeshlibs in the debhelper suite
does. If your package also has a udeb that provides a shared library,
dh_makeshlibs can automatically generate the udeb:
lines if you specify the name of the udeb with the --add-udeb
option.
This is necessary in order to reserve the directories for use in cross-installation of library packages from other architectures, as part of multiarch.
This is necessary for architecture-dependant headers file to coexist in a multiarch setup.
This directory is used as mount point to mount virtual filesystems to get access to kernel information.
These directories are used to store translators and as a set of standard names for mount points, respectively.
For packages that do not require any of these things, integration is a no-op, of course.
Many of the things that systemd prohibits are inherently problematic, irrespective of systemd.
Note that the Alias= setting in systemd unit files can be used to alleviate some problematic cases.
This has the disadvantage of creating two separate and not synchronized sets of
administrator-defined service parameterization information, one for systemd
units and one for init.d scripts.
Readiness protocols are a communication mechanism between daemons and systemd that allow systemd to delay starting client processes until a server process is ready to service their requests. systemd supports several such protocols.
In other words, the user should not be able to change any access permissions except where that is a part of the daemon's function. This means not running services with the accounts of real, human, users, of course.
update-rc.d no longer has the ability to explicitly configure run
levels on the command line. They must instead be part of the LSB Header in an
init.d script (init.d
scripts, Section 9.3.7).
On BSD operating systems, /etc/rc.boot is a file.
This is a subtle difference from some historical systems, where
rc.local need only be sourceable by the default shell.
/lib/lsb/init-functions, which assists in writing LSB-compliant init scripts, may fail if set -e is in effect and echoing status messages to the console fails, for example.
Creating, modifying or removing a file in /usr/lib/mime/packages/
using maintainer scripts will not activate the trigger. In that case, it can
be done by calling dpkg-trigger --no-await /usr/lib/mime/packages
from the maintainer script after creating, modifying, or removing the file.
If you are using GCC, -fPIC produces code with relocatable position independent code, which is required for most architectures to create a shared library, with i386 and perhaps some others where non position independent code is permitted in a shared library.
Position independent code may have a performance penalty, especially on i386. However, in most cases the speed penalty must be measured against the memory wasted on the few architectures where non position independent code is even possible.
Some of the reasons why this might be required is if the library contains hand crafted assembly code that is not relocatable, the speed penalty is excessive for compute intensive libs, and similar reasons.
Some of the reasons for linking static libraries with the -fPIC flag are if, for example, one needs a Perl API for a library that is under rapid development, and has an unstable API, so shared libraries are pointless at this phase of the library's development. In that case, since Perl needs a library with relocatable code, it may make sense to create a static library with relocatable code. Another reason cited is if you are distilling various libraries into a common shared library, like mklibs does in the Debian installer project.
You might also want to use the options --remove-section=.comment and --remove-section=.note on both shared libraries and executables, and --strip-debug on static libraries.
A common example are the so-called "plug-ins", internal shared
objects that are dynamically loaded by programs using dlopen(3).
These files store, among other things, all libraries on which that shared
library depends. Unfortunately, if the .la file is present and
contains that dependency information, using libtool when linking
against that library will cause the resulting program or library to be linked
against those dependencies as well, even if this is unnecessary. This can
create unneeded dependencies on shared library packages that would otherwise be
hidden behind the library ABI, and can make library transitions to new SONAMEs
unnecessarily complicated and difficult to manage.
Single UNIX Specification, version 3, which is also IEEE 1003.1-2004 (POSIX),
and is available on the World Wide Web from The Open Group after
free registration.
These features are in widespread use in the Linux community and are implemented
in all of bash, dash, and ksh, the most common shells users may wish to use as
/bin/sh.
This is necessary to allow top-level directories to be symlinks. If linking
/var/run to /run were done with the relative symbolic
link ../run, but /var were a symbolic link to
/srv/disk1, the symbolic link would point to /srv/run
rather than the intended target.
This notification could be done via a (low-priority) debconf message, or an echo (printf) statement.
It's better to use mkfifo rather than mknod to create
named pipes so that automated checks for packages incorrectly creating device
files with mknod won't have false positives.
The dpkg-maintscript-helper tool, available from the
dpkg package, can help for this task.
Rationale: There are two problems with hard links. The first is that some
editors break the link while editing one of the files, so that the two files
may unwittingly become unlinked and different. The second is that
dpkg might break the hard link while upgrading
conffiles.
The traditional approach to log files has been to set up ad hoc log rotation schemes using simple shell scripts and cron. While this approach is highly customizable, it requires quite a lot of sysadmin work. Even though the original Debian system helped a little by automatically installing a system which can be used as a template, this was deemed not enough.
The use of logrotate, a program developed by Red Hat, is better,
as it centralizes log management. It has both a configuration file
(/etc/logrotate.conf) and a directory where packages can drop
their individual log rotation configurations (/etc/logrotate.d).
When a package is upgraded, and the owner or permissions of a file included in the package has changed, dpkg arranges for the ownership and permissions to be correctly set upon installation. However, this does not extend to directories; the permissions and ownership of directories already on the system does not change on install or upgrade of packages. This makes sense, since otherwise common directories like /usr would always be in flux. To correctly change permissions of a directory the package owns, explicit action is required, usually in the postinst script. Care must be taken to handle downgrades as well, in that case.
Ordinary files installed by dpkg (as opposed to
conffiles and other similar objects) normally have their
permissions reset to the distributed permissions when the package is
reinstalled. However, the use of dpkg-statoverride overrides this
default behavior.
Internally, the package system normalizes the GNU triplets and the Debian arches into Debian arch triplets (which are kind of inverted GNU triplets), with the first component of the triplet representing the libc and ABI in use, and then does matching against those triplets. However, such triplets are an internal implementation detail that should not be used by packages directly. The libc and ABI portion is handled internally by the package system based on the os and cpu.
The Debian base system already provides an editor and a pager program.
If it is not possible to establish both locks, the system shouldn't wait for the second lock to be established, but remove the first lock, wait a (random) time, and start over locking again.
You will need to depend on liblockfile1 (>>1.01) to use these functions.
There are two traditional permission schemes for mail spools: mode 600 with all mail delivery done by processes running as the destination user, or mode 660 and owned by group mail with mail delivery done by a process running as a system user in group mail. Historically, Debian required mode 660 mail spools to enable the latter model, but that model has become increasingly uncommon and the principle of least privilege indicates that mail systems that use the first model should use permissions of 600. If delivery to programs is permitted, it's easier to keep the mail system secure if the delivery agent runs as the destination user. Debian Policy therefore permits either scheme.
This implements current practice, and provides an actual policy for usage of the xserver virtual package which appears in the virtual packages list. In a nutshell, X servers that interface directly with the display and input hardware or via another subsystem (e.g., GGI) should provide xserver. Things like Xvfb, Xnest, and Xprt should not.
"New terminal window" does not necessarily mean a new top-level X window directly parented by the window manager; it could, if the terminal emulator application were so coded, be a new "view" in a multiple-document interface (MDI).
For the purposes of Debian Policy, a "font for the X Window System" is one which is accessed via X protocol requests. Fonts for the Linux console, for PostScript renderer, or any other purpose, do not fit this definition. Any tool which makes such fonts available to the X Window System, however, must abide by this font policy.
This is because the X server may retrieve fonts from the local file system or over the network from an X font server; the Debian package system is empowered to deal only with the local file system.
Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client binary on the local file system, whereas X resources are stored in the X server and affect all connecting clients.
It is not very hard to write a man page. See the Man-Page-HOWTO,
man(7), the examples created by dh_make, the helper
program help2man, or the directory
/usr/share/doc/man-db/examples.
Supporting this in man often requires unreasonable processing time
to find a manual page or to report that none exists, and moves knowledge into
man's database that would be better left in the file system. This support is
therefore deprecated and will cease to be present in the future.
man will automatically detect whether UTF-8 is in use. In future,
all manual pages will be required to use UTF-8.
At the time of writing, Chinese and Portuguese are the main languages with such
differences, so pt_BR, zh_CN, and zh_TW
are all allowed.
Normally, info documents are generated from Texinfo source. To include this information in the generated info document, if it is absent, add commands like:
@dircategory Individual utilities
@direntry
* example: (example). An example info directory entry.
@end direntry
to the Texinfo source of the document and ensure that the info documents are rebuilt from source during the package build.
The system administrator should be able to delete files in
/usr/share/doc/ without causing any programs to break.
Please note that this does not override the section on changelog files below,
so the file /usr/share/doc/package/changelog.Debian.gz
must refer to the changelog for the current version of package in
question. In practice, this means that the sources of the target and the
destination of the symlink must be the same (same source package and version).
At this phase of the transition, we no longer require a symbolic link in
/usr/doc/. At a later point, policy shall change to make the
symbolic links a bug.
The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package.
In particular, /usr/share/common-licenses/Apache-2.0,
/usr/share/common-licenses/Artistic,
/usr/share/common-licenses/GPL-1,
/usr/share/common-licenses/GPL-2,
/usr/share/common-licenses/GPL-3,
/usr/share/common-licenses/LGPL-2,
/usr/share/common-licenses/LGPL-2.1,
/usr/share/common-licenses/LGPL-3,
/usr/share/common-licenses/GFDL-1.2, and
/usr/share/common-licenses/GFDL-1.3 respectively. The University
of California BSD license is also included in base-files as
/usr/share/common-licenses/BSD, but given the brevity of this
license, its specificity to code whose copyright is held by the Regents of the
University of California, and the frequency of minor wording changes, its text
should be included in the copyright file rather than referencing this file.
Rationale: People should not have to look in places for upstream changelogs merely because they are given different names or are distributed in HTML format.
dpkg is targeted primarily at Debian, but may work on or be ported
to other systems.
This is so that the control file which is produced has the right permissions
This is not currently detected when building source packages, but only when extracting them.
Hard links may be permitted at some point in the future, but would require a fair amount of work.
Setgid directories are allowed.
Renaming a file is not treated specially - it is seen as the removal of the old file (which generates a warning, but is otherwise ignored), and the creation of the new one.
Debian Policy Manual
version 3.9.7.0, 2014-11-21