[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Packaging Manual is policy

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


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

     [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

     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

     Its format is the same as that of a version number except that no
     epoch or Debian revision is allowed - see Chapter 5, `Version

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

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