X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=policy.sgml;h=404dc7373f80cdc20bf793e064d7163e3885518f;hp=1743552e0f16e5d104fc99c8b7ed6221b9b9dee4;hb=HEAD;hpb=f545dfd88c291812520adee2147723a47e16f220 diff --git a/policy.sgml b/policy.sgml index 1743552..404dc73 100644 --- a/policy.sgml +++ b/policy.sgml @@ -229,9 +229,8 @@ Russ Allbery Bill Allombert - Andrew McMillan - Manoj Srivastava - Colin Watson + Andreas Barth + Jonathan Nieder

@@ -1746,11 +1745,14 @@ zope.

The maintainer name and email address used in the changelog - should be the details of the person uploading this - version. They are not necessarily those of the - usual package maintainer. - If the developer uploading the package is not one of the usual - maintainers of the package (as listed in + should be the details of the person who prepared this release of + the package. They are not necessarily those of the + uploader or usual package maintainer. + 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 @@ -1929,6 +1931,10 @@ zope. any target that these targets depend on must also be non-interactive.

+

+ For packages in the main archive, no required targets + may attempt network access. +

The targets are as follows: @@ -2367,8 +2373,7 @@ endif This is an optional, recommended configuration file for the uscan utility which defines how to automatically scan ftp or http sites for newly available updates of the - package. This is used - by and other Debian QA + package. This is used Debian QA tools to help with quality control and maintenance of the distribution as a whole.

@@ -2557,7 +2562,9 @@ Package: libc6 the field name is Package and the field value libc6.

- +

Empty field values are only permitted in source package control files + (debian/control). Such fields are ignored. +

A paragraph must not contain more than one instance of a particular field name. @@ -2700,6 +2707,7 @@ Package: libc6 file. These tools are responsible for removing the line breaks from such fields when using fields from debian/control to generate other control files. + They are also responsible for discarding empty fields.

@@ -3674,7 +3682,7 @@ Files:

The special value byhand for the section in a .changes file indicates that the file in question - is not an ordinary package file and must by installed by + is not an ordinary package file and must be installed by hand by the distribution maintainers. If the section is byhand the priority should be -.

@@ -6918,6 +6926,20 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) exceptions to the FHS apply: + +

+ The FHS requirement that architecture-independent + application-specific static files be located in + /usr/share is relaxed to a suggestion. + + In particular, a subdirectory of /usr/lib may + be used by a package (or a collection of packages) to hold a + mixture of architecture-independent and + architecture-dependent files. However, when a directory is + entirely composed of architecture-independent files, it + should be located in /usr/share. +

+

The optional rules related to user specific @@ -6959,8 +6981,18 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) This is necessary in order to reserve the directories for use in cross-installation of library packages from other - architectures, as part of the planned deployment of - multiarch. + architectures, as part of multiarch. + +

+

+ The requirement for C and C++ headers files to be + accessible through the search path + /usr/include/ is amended, permitting files to + be accessible through the search path + /usr/include/triplet where + triplet is as above. + This is necessary for architecture-dependant headers + file to coexist in a multiarch setup.

@@ -7029,6 +7061,21 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) kernel information.

+ +

+ The /var/www directory is additionally allowed. +

+ + +

+ The requirement for /usr/local/lib<qual> + to exist if /lib<qual> or + /usr/lib<qual> exists (where + lib<qual> is a variant of + lib such as lib32 or + lib64) is removed. +

+

On GNU/Hurd systems, the following additional @@ -7309,6 +7356,35 @@ rmdir /usr/local/share/emacs 2>/dev/null || true 65535: + +

+ This value must not be used, because it was + the error return sentinel value when uid_t + was 16 bits. +

+ + + 65536-4294967293: + +

+ Dynamically allocated user accounts. By + default adduser will not allocate UIDs + and GIDs in this range, to ease compatibility with + legacy systems where uid_t is still 16 + bits. +

+ + + 4294967294: + +

+ (uid_t)(-2) == (gid_t)(-2) must not be + used, because it is used as the anonymous, unauthenticated + user by some NFS implementations. +

+ + + 4294967295:

(uid_t)(-1) == (gid_t)(-1) must @@ -8054,75 +8130,38 @@ Reloading description configuration...done. Menus

- Packages shipping applications that comply with minimal requirements - described below for integration with desktop environments should - register these applications in the desktop menu, following the - FreeDesktop standard, using text files called - desktop entries. Their format is described in the - Desktop Entry Specification at - - and complementary information can be found in the - Desktop Menu Specification at - . + The Debian menu package provides a standard + interface between packages providing applications and + menu programs (either X window managers or + text-based menu programs such as pdmenu).

- The desktop entry files are installed by the packages in the - directory /usr/share/applications and the FreeDesktop - menus are refreshed using dpkg triggers. It is therefore - not necessary to depend on packages providing FreeDesktop menu - systems. + All packages that provide applications that need not be + passed any special command line arguments for normal + operation should register a menu entry for those + applications, so that users of the menu package + will automatically get menu entries in their window + managers, as well in shells like pdmenu.

- Entries displayed in the FreeDesktop menu should conform to the - following minima for relevance and visual integration. - - - - Unless hidden by default, the desktop entry must point to a PNG - or SVG icon with a transparent background, providing at least - the 22×22 size, and preferably up to 64×64. The icon - should be neutral enough to integrate well with the default icon - themes. It is encouraged to ship the icon in the default - hicolor icon theme directories, or to use an existing - icon from the hicolor theme. - - - - If the menu entry is not useful in the general case as a - standalone application, the desktop entry should set the - NoDisplay key to true, so that it can be - configured to be displayed only by those who need it. - - - - In doubt, the package maintainer should coordinate with the - maintainers of menu implementations through the - debian-desktop mailing list in order to avoid problems - with categories or bad interactions with other icons. Especially - for packages which are part of installation tasks, the contents - of the NotShowIn/OnlyShowIn keys should be - validated by the maintainers of the relevant environments. - - + Menu entries should follow the current menu policy.

- Since the FreeDesktop menu is a cross-distribution standard, the - desktop entries written for Debian should be forwarded upstream, - where they will benefit to other users and are more likely to - receive extra contributions such as translations. + The menu policy can be found in the menu-policy + files in the debian-policy package. + It is also available from the Debian web mirrors at + .

-

- Packages can, to be compatible with Debian additions to some window - managers that do not support the FreeDesktop standard, also provide a - Debian menu file, following the Debian menu policy, - which can be found in the menu-policy files in the - debian-policy package. It is also available from the Debian - web mirrors at . +

+ Please also refer to the Debian Menu System + documentation that comes with the menu + package for information about how to register your + applications.

@@ -8130,109 +8169,42 @@ Reloading description configuration...done. Multimedia handlers

- Media types (formerly known as MIME types, Multipurpose Internet Mail - Extensions, RFCs 2045-2049) is a mechanism for encoding files and - data streams and providing meta-information about them, in particular - their type and format (e.g. image/png, text/html, - audio/ogg). + MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) + is a mechanism for encoding files and data streams and + providing meta-information about them, in particular their + type (e.g. audio or video) and format (e.g. PNG, HTML, + MP3).

- Registration of media type handlers allows programs like mail + Registration of MIME type handlers allows programs like mail user agents and web browsers to invoke these handlers to - view, edit or display media types they don't support directly. + view, edit or display MIME types they don't support directly.

- There are two overlapping systems to associate media types to programs - which can handle them. The mailcap system is found on a - large number of Unix systems. The FreeDesktop system is - aimed at Desktop environments. In Debian, FreeDesktop entries are - automatically translated in mailcap entries, therefore packages - already using desktop entries should not use the mailcap system - directly. + Packages which provide programs to view/show/play, compose, edit or + print MIME types should register them as such by placing a file in + format (RFC 1524) in the directory + /usr/lib/mime/packages/. The file name should be the + binary package's name.

- - Registration of media type handlers with desktop entries - -

- Packages shipping an application able to view, edit or point to - files of a given media type, or open links with a given URI scheme, - should list it in the MimeType key of the application's - desktop entry. For URI schemes, - the relevant MIME types are x-scheme-handler/* (e.g. - x-scheme-handler/https). -

- - - - Registration of media type handlers with mailcap entries - -

- Packages that are not using desktop entries for registration should - install a file in format (RFC - 1524) in the directory /usr/lib/mime/packages/. The - file name should be the binary package's name. -

- -

- The mime-support package provides the - update-mime program, which integrates these - registrations in the /etc/mailcap file, using dpkg - triggers - 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. - . - -

- Packages installing desktop entries should not install mailcap - entries for the same program, because the - mime-support package already reads desktop - entries. -

- -

- Packages using these facilities should not depend on, - recommend, or suggest mime-support. -

- - - - Providing media types to files - -

- The media type of a file is discovered by inspecting the file's - extension or its pattern, and - interrogating a database associating them with media types. -

- -

- To support new associations between media types and files, their - characteristic file extensions and magic patterns should be - registered to the IANA (Internet Assigned Numbers Authority). See - and RFC 6838 - for details. This information will then propagate to the systems - discovering file media types in Debian, provided by the - shared-mime-info, - mime-support and file - packages. If registration and propagation can not be waited for, - support can be asked to the maintainers of the packages mentioned - above. -

- -

- For files that are produced and read by a single application, it - is also possible to declare this association to the - Shared MIME Info system by installing in the directory - /usr/share/mime/packages a file in the XML format - specified at . -

- +

+ The mime-support package provides the + update-mime program, which integrates these + registrations in the /etc/mailcap file, using dpkg + triggers + 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. + . + Packages using this facility should not depend on, + recommend, or suggest mime-support. +

@@ -8536,7 +8508,17 @@ fi renamed. If a consensus cannot be reached, both programs must be renamed.

- +

+ Binary executables must not be statically linked with the GNU C + library, since this prevents the binary from benefiting from + fixes and improvements to the C library without being rebuilt + and complicates security updates. This requirement may be + relaxed for binary executables whose intended purpose is to + diagnose and fix the system in situations where the GNU C + library may not be usable (such as system recovery shells or + utilities like ldconfig) or for binary executables where the + security benefits of static linking outweigh the drawbacks. +

By default, when a package is being built, any binaries created should include debugging information, as well as @@ -8945,6 +8927,7 @@ fname () { would point to /srv/run rather than the intended target. + Symbolic links must not traverse above the root directory.

@@ -9802,15 +9785,16 @@ done Cgi-bin executable files are installed in the directory -/usr/lib/cgi-bin/cgi-bin-name +/usr/lib/cgi-bin - or a subdirectory of that directory, and should be - referred to as + or a subdirectory of that directory, and the script -http://localhost/cgi-bin/cgi-bin-name +/usr/lib/cgi-bin/.../cgi-bin-name + + should be referred to as + +http://localhost/cgi-bin/.../cgi-bin-name - (possibly with a subdirectory name - before cgi-bin-name). @@ -9842,7 +9826,7 @@ http://localhost/cgi-bin/cgi-bin-name doc-base package. If access to the web document root is unavoidable then use -/var/www +/var/www/html as the Document Root. This might be just a symbolic link to the location where the system administrator @@ -10678,45 +10662,77 @@ END-INFO-DIR-ENTRY

- + Additional documentation

- Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - /usr/share/doc/package, where - package is the name of the package, and - compressed with gzip -9 unless it is small. -

+ Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (READMEs, FAQs, and so forth) that come with the + source package in the binary package. However, you don't need + to install the instructions for building and installing the + package, of course! +

- If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed.

+ Plain text documentation should be compressed with gzip + -9 unless it is small. +

- It is often a good idea to put text information files - (READMEs, changelogs, and so forth) that come with - the source package in /usr/share/doc/package - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!

+ If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package () + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package package is conventionally + named package-doc + (or package-doc-language-code if there are + separate documentation packages for multiple languages). +

+ +

+ Additional documentation included in the package should be + installed under /usr/share/doc/package. + If the documentation is packaged separately, + as package-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (/usr/share/doc/package-doc in this + example). However, installing the documentation into the + documentation directory of the main package is preferred since + it is independent of the packaging method and will be easier for + users to find. +

+ +

+ Any separate package providing documentation must still install + standard documentation files in its + own /usr/share/doc directory as specified in the + rest of this policy. See, for example, + and . +

Packages must not require the existence of any files in /usr/share/doc/ in order to function - The system administrator should be able to - delete files in /usr/share/doc/ without causing - any programs to break. - . - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - /usr/share/package/ with symbolic links from - /usr/share/doc/package. + The system administrator should be able to delete files + in /usr/share/doc/ without causing any programs + to break. + . Any files that are used or read by programs but + are also useful as stand alone documentation should be installed + elsewhere, such as + under /usr/share/package/, and then + included via symbolic links + in /usr/share/doc/package.

@@ -10736,18 +10752,6 @@ END-INFO-DIR-ENTRY

- -

- Former Debian releases placed all additional documentation - in /usr/doc/package. This has been - changed to /usr/share/doc/package, - and packages must not put documentation in the directory - /usr/doc/package. - 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. - -

@@ -10758,16 +10762,16 @@ END-INFO-DIR-ENTRY via HTML.

- If your package comes with extensive documentation in a + If the package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in a binary - package, in the directory - /usr/share/doc/appropriate-package or - its subdirectories. - The rationale: The important thing here is that HTML - docs should be available in some package, not - necessarily in the main binary package. + package. + Rationale: The important thing here is that HTML + documentation should be available from some + binary package. + The documentation must be installed as specified in + .