Re: Packaging Manual is policy
Hi,
>>"Joey" == Joey Hess <joey@kitenet.net> writes:
Joey> Julian Gilbey wrote:
>> Reading bug #31645, it seems clear that the Packaging Manual was
>> accepted as policy, although Joey had reservations.
>>
>> Should I go ahead and make the modifications Manoj proposed?
Joey> I continue to disagree that this has any business being in policy.
I think, then, there are a few things that should be moved
from the packaging to the policy manual. I would specifically point
to chapter 5, on version numbering; that has gone beyond merely being
what dpkg expects, and should be in policy proper. The ways that the
maintainer scripts are called, and thus how they should be written,
should also be considered a policy matter, IMHO.
I suspect there are other things I may have missed.
I agree that the packaging manual has aspects of a recipe for
constructing apackage, and that would change as the packaging tools
morph; but it also contains policy strictures buried in the recipe.
As I see it, accepting the packaging manual as having the
weight of policy does no harm, and goves us time to pull out the
policy aspects of thepackaging manual into the policy.sgml.
manoj
Things I think should be considered policy (actually, most of the
latter chapter had things in it that should be in policy)
----------------------------------------------------------------------
2.4. Time Stamps
----------------
Maintainers are encouraged to preserve the modification times of the
upstream source files in a package, as far as is reasonably possible.
[1]
[1] 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.
3.2.1. `debian/rules' - the main building script
[Required targets in a rules file]
build `binary', `binary-arch', `binary-indep' `clean'
3.2.5. `debian/files'
Must not ship in a shipped source package
4. Control files and their fields
4.2.1. `Package'
----------------
The name of the binary package. Package names consist of the
alphanumerics and `+' `-' `.' (plus, minus and full stop). [1]
[1] The characters `@' `:' `=' `t't> `_' (at, colon, equals, percent
and underscore) used to be legal and are still accepted when
found in a package file, but may not be used in new packages
They must be at least two characters and must start with an
alphanumeric. In current versions of dpkg they are sort of
case-sensitive[1]; use lowercase package names unless the package
you're building (or referring to, in other fields) is already using
uppercase.
[1] This is a bug.
4.2.2. `Version'
----------------
This lists the source or binary package's version number - see Chapter
5, `Version numbering'.
4.2.4. `Maintainer'
-------------------
The package maintainer's name and email address. The name should come
first, then the email address inside angle brackets `<>' (in RFC822
format).
If the maintainer's name contains a full stop then the whole field
will not work directly as an email address due to a misfeature in the
syntax specified in RFC822; a program using this field as an address
must check for this and correct the problem if necessary (for example
by putting the name in round brackets and moving it to the end, and
bringing the email address forward).
In a `.changes' file or parsed changelog data this contains the name
and email address of the person responsible for the particular version
in question - this may not be the package's usual maintainer.
4.2.6. Package interrelationship fields: `Depends', `Pre-Depends',
`Recommends' `Suggests', `Conflicts', `Provides', `Replaces'
4.2.8. `Essential'
------------------
This is a boolean field which may occur only in the control file of a
binary package (or in the `Packages' file) or in a per-package fields
paragraph of a main source control data file.
4.2.9. `Section' and `Priority'
-------------------------------
4.2.13. `Standards-Version'
---------------------------
The most recent version of the standards (the `dpkg' programmers' and
policy manuals and associated texts) with which the package complies.
This is updated manually when editing the source package to conform to
newer standards; it can sometimes be used to tell when a package needs
attention.
Its format is the same as that of a version number except that no
epoch or Debian revision is allowed - see Chapter 5, `Version
numbering'.
4.2.14. `Distribution'
----------------------
4.2.15. `Urgency'
-----------------
5. Version numbering
All of chapter 5
6. Package maintainer scripts and installation procedure
--------------------------------------------------
This is no lomger merely the way dpkg works; because of the
installed base aspect, this should be considered policy.
-----------------------------------------------------
7.2. Notes about writing descriptions
-------------------------------------
_Always_ start extended description lines with at least one whitespace
character. Fields in the control file and in the Packages file are
separated by field names starting in the first column, just as message
header fields are in RFC822. Forgetting the whitespace will cause
`dpkg-deb' [1] to produce a syntax error when trying to build the
package. If you force it to build anyway `dpkg' will refuse to install
the resulting mess.
[1] Version 0.93.23 or later.
_Do not_ include any completely _empty_ lines. These separate
different records in the Packages file and different packages in the
`debian/control' file, and are forbidden in package control files. See
the previous paragraph for what happens if you get this wrong.
The single line synopsis should be kept brief - certainly under 80
characters. `dselect' displays between 25 and 49 characters without
panning if you're using an 80-column terminal, depending on what
display options are in effect.
Do not include the package name in the synopsis line. The display
software knows how to display this already, and you do not need to
state it. Remember that in many situations the user may only see the
synopsis line - make it as informative as you can.
The extended description should describe what the package does and how
it relates to the rest of the system (in terms of, for example, which
subsystem it is which part of).
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. The description field needs to make sense to anyone,
even people who have no idea about any of the things the package deals
with.
Put important information first, both in the synopis and extended
description. Sometimes only the first part of the synopsis or of the
description will be displayed. You can assume that there will usually
be a way to see the whole extended description.
You may include information about dependencies and so forth in the
extended description, if you wish.
Do not use tab characters. Their effect is not predictable.
Do not try to linewrap the summary (the part on the same line as the
field name `Description') into the extended description. This will not
work correctly when the full description is displayed, and makes no
sense where only the summary is available.
----------------------------------------------------------------------
8.2. Dependencies - `Depends', `Recommends', `Suggests', `Pre-Depends'
----------------------------------------------------------------------
8.5.1. Overwriting files in other packages
------------------------------------------
Firstly, as mentioned before, it is usually an error for a package to
contains files which are on the system in another package, though
currently the `--force-overwrite' flag is enabled by default,
downgrading the error to a warning,
If the overwriting package declares that it replaces the one
containing the file being overwritten then `dpkg' will proceed, and
replace the file from the old package with that from the new. The file
will no longer be listed as `owned' by the old package.
8.5.2. Replacing whole packages, forcing their removal
------------------------------------------------------
8.6. Defaults for satisfying dependencies - ordering
----------------------------------------------------
9. Configuration file handling
------------------------------
---------------------------------------------------------
The following are what I am unsure about:
----------------------------------------------------------------------
3.4.1. Restrictions on objects in source packages
-------------------------------------------------
The source package may not contain any hard links [1] [2], device
special files, sockets or setuid or setgid files. [3]
[1] This is not currently detected when building source packages, but
only when extracting them.
[2] Hard links may be permitted at some point in the future, but
would require a fair amount of work.
[3] Setgid directories are allowed.
----------------------------------------------------------------------
--
Q: What do you get when you cross a mobster with an international
standard? A: You get someone who makes you an offer that you can't
understand!
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
Reply to: