X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=1743552e0f16e5d104fc99c8b7ed6221b9b9dee4;hb=ba679bff76f5b9152f43d5bc901b9b3aad257479;hp=1390cf41c5e0d69d6de6135e806776c1c181c73d;hpb=f812bda88f43e6af288b21d37a5a6e34d675190d;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 1390cf4..1743552 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1274,7 +1274,7 @@ zope.

Essential is defined as the minimal set of functionality that must be available and usable on the system at all times, even - when packages are in an unconfigured (but unpacked) state. + when packages are in the "Unpacked" state. Packages are tagged essential for a system using the Essential control field. The format of the Essential control field is described in update-alternatives is not used, then each package must use Conflicts to ensure that other packages are - de-installed. (In this case, it may be appropriate to + removed. (In this case, it may be appropriate to specify a conflict against earlier versions of something that previously did not use update-alternatives; this is an exception to @@ -1916,7 +1916,8 @@ zope.

The following targets are required and must be implemented by debian/rules: clean, binary, - binary-arch, binary-indep, and build. + binary-arch, binary-indep, build, + build-arch and build-indep. These are the targets called by dpkg-buildpackage.

@@ -2541,7 +2542,7 @@ endif composed of US-ASCII characters excluding control characters, space, and colon (i.e., characters in the ranges 33-57 and 59-126, inclusive). Field names must not begin with the comment - character, #. + character, #, nor with the hyphen character, -.

@@ -2758,6 +2759,7 @@ Package: libc6 Uploaders Homepage Vcs-Browser, Vcs-Git, et al. + Dgit Standards-Version (recommended) Build-Depends et al Package-List (recommended) @@ -3839,6 +3841,26 @@ Checksums-Sha256: this value is assumed for paragraphs lacking this field.

+ + + Dgit + +

+ Folded field containing a single git commit hash, presented in + full, followed optionally by whitespace and other data to be + defined in future extensions. +

+ +

+ Declares that the source package corresponds exactly to a + referenced commit in a Git repository available at the canonical + location called dgit-repos, used by dgit, a + bidirectional gateway between the Debian archive and Git. The + commit is reachable from at least one reference whose name matches + refs/dgit/*. See the manual page of dgit for + further details. +

+ @@ -4068,7 +4090,7 @@ Checksums-Sha256: pre-dependencies (Pre-Depends) may be assumed to be available. Pre-dependencies will have been configured at least once, but at the time the preinst is - called they may only be in an unpacked or "Half-Configured" + called they may only be in an "Unpacked" or "Half-Configured" state if a previous version of the pre-dependency was completely configured and has not been removed since then. @@ -4082,7 +4104,7 @@ Checksums-Sha256: partly from the new version or partly missing, so the script cannot rely on files included in the package. Package dependencies may not be available. Pre-dependencies will be - at least unpacked following the same rules as above, except + at least "Unpacked" following the same rules as above, except they may be only "Half-Installed" if an upgrade of the pre-dependency failed. This can happen if the new version of the package no @@ -4101,7 +4123,7 @@ Checksums-Sha256: most-recently-configured-version The files contained in the package will be unpacked. All - package dependencies will at least be unpacked. If there + package dependencies will at least be "Unpacked". If there are no circular dependencies involved, all package dependencies will be configured. For behavior in the case of circular dependencies, see the discussion @@ -4125,7 +4147,7 @@ Checksums-Sha256: will have previously been configured and not removed. However, dependencies may not be configured or even fully unpacked in some error situations. - For example, suppose packages foo and bar are installed + 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, @@ -4162,7 +4184,7 @@ Checksums-Sha256: at least "Half-Installed". All package dependencies will at least be "Half-Installed" and will have previously been configured and not removed. If there was no error, all - dependencies will at least be unpacked, but these actions + dependencies will at least be "Unpacked", but these actions may be called in various error states where dependencies are only "Half-Installed" due to a partial upgrade. @@ -4191,7 +4213,7 @@ Checksums-Sha256: The postrm script is called after the package's files have been removed or replaced. The package whose postrm is being called may have - previously been deconfigured and only be unpacked, at which + previously been deconfigured and only be "Unpacked", at which point subsequent package changes do not consider its dependencies. Therefore, all postrm actions may only rely on essential packages and must gracefully skip @@ -4254,7 +4276,7 @@ fi - If a version of the package is already installed, call + If a version of the package is already "Installed", call old-prerm upgrade new-version @@ -4369,7 +4391,7 @@ fi Otherwise, if the package had some configuration files from a previous version installed (i.e., it - is in the "configuration files only" state): + is in the "Config-Files" state): new-preinst install old-version @@ -4394,7 +4416,7 @@ fi If the error-unwind fails, the package is in a "Half-Installed" phase, and requires a reinstall. If the error unwind works, the - package is in a not installed state. + package is in the "Not-Installed" state. @@ -4532,7 +4554,7 @@ fi It is noted in the status database as being in a - sane state, namely not installed (any conffiles + sane state, namely "Not-Installed" (any conffiles it may have are ignored, rather than being removed by dpkg). Note that disappearing packages do not have their prerm @@ -4558,7 +4580,7 @@ fi

The new package's status is now sane, and recorded as - "unpacked". + "Unpacked".

@@ -4595,7 +4617,7 @@ fi

No attempt is made to unwind after errors during configuration. If the configuration fails, the package is in - a "Failed Config" state, and an error message is generated. + a "Half-Configured" state, and an error message is generated.

@@ -4715,8 +4737,8 @@ fi dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols |. In such a case, - if any one of the alternative packages is installed, that - part of the dependency is considered to be satisfied. + that part of the dependency can be satisfied by any one of + the alternative packages.

@@ -5047,11 +5069,11 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] be unpacked the pre-dependency can be satisfied if the depended-on package is either fully configured, or even if the depended-on - package(s) are only unpacked or in the "Half-Configured" + package(s) are only in the "Unpacked" or the "Half-Configured" state, provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case, both the - previously-configured and currently unpacked or + previously-configured and currently "Unpacked" or "Half-Configured" versions must satisfy any version clause in the Pre-Depends field.

@@ -5406,7 +5428,7 @@ Depends: foo-data (>= 1.2-3) dpkg does not know of any files it still contains, it is considered to have "disappeared". It will be marked as not wanted on the system (selected for - removal) and not installed. Any conffiles + removal) and "Not-Installed". Any conffiles details noted for the package will be ignored, as they will have been taken over by the overwriting package. The package's postrm script will be run with a @@ -6999,15 +7021,14 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) stable release of Debian supports /run.

- -

- The following directories in the root filesystem are - additionally allowed: /sys and - /selinux. These directories - are used as mount points to mount virtual filesystems - to get access to kernel information. -

- + +

+ The /sys directory in the root filesystem is + additionally allowed. This directory is used as + mount point to mount virtual filesystems to get access to + kernel information. +

+

On GNU/Hurd systems, the following additional @@ -8033,38 +8054,75 @@ Reloading description configuration...done. Menus

- 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). + 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 + .

- 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. + 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.

- Menu entries should follow the current menu policy. + 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. + +

- 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 - . + 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.

-

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

+ 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 .

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

- 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). + 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).

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

-

- 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. -

+ + 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 . +

+ @@ -8852,7 +8977,9 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

- A symbolic link pointing to a compressed file should always + A symbolic link pointing to a compressed file (in the sense + that it is meant to be uncompressed with unzip + or zless etc.) should always have the same file extension as the referenced file. (For example, if a file foo.gz is referenced by a symbolic link, the filename of the link has to end with @@ -8986,8 +9113,10 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq package is purged. - Obsolete configuration files without local changes may be - removed by the package during upgrade. + Obsolete configuration files without local changes should be + removed by the package during upgrade. + The dpkg-maintscript-helper tool, available from the + dpkg package, can help for this task.

@@ -9470,6 +9599,23 @@ done

+ + + File names + +

+ The name of the files installed by binary packages in the system PATH + (namely /bin, /sbin, /usr/bin, + /usr/sbin and /usr/games) must be encoded in + ASCII. +

+ +

+ The name of the files and directories installed by binary packages + outside the system PATH must be encoded in UTF-8 and should be + restricted to ASCII when it is possible to do so. +

+ @@ -9668,24 +9814,7 @@ http://localhost/cgi-bin/cgi-bin-name -

Access to HTML documents

- -

- HTML documents for a package are stored in - /usr/share/doc/package - and can be referred to as - -http://localhost/doc/package/filename - -

- -

- The web server should restrict access to the document - tree so that only clients on the same host can read - the documents. If the web server does not support such - access controls, then it should not provide access at - all, or ask about providing access during installation. -

+

(Deleted)

 @@ -12047,6 +12176,11 @@ END-INFO-DIR-ENTRY there is a time, after it has been diverted but before dpkg has installed the new version, when the file does not exist.

+ +

+ Do not attempt to divert a conffile, as dpkg does not + handle it well. +