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

Re: Packaging Manual is policy

Manoj Srivastava wrote:
>         I think, then, there are a few things that should be moved
>  from the packaging to the policy manual.

Agreed. But I think we should not rush this, and should go through the
normal amendment process for these, with the only difference being we
already have the text for most of them written.

Things I agree to below can be considered to have my second.

> 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

I tend to disagree this needs to be in policy. 

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


> 4.2.2. `Version'
> ----------------
>      This lists the source or binary package's version number - see Chapter
>      5, `Version numbering'.

Huh? Are you saying that this description of the existance of the Version:
field belongs in policy?

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

I don't think this belongs in policy, becuase it's just an informational
note, and policy doesn't prohibit it anyway.

> 4.2.6. Package interrelationship fields: `Depends', `Pre-Depends',
> `Recommends' `Suggests', `Conflicts', `Provides', `Replaces'

You think the existance of these fields should be in policy?

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

Hm, am I missing something and there is some other place people might try to
put it?

> 4.2.9. `Section' and `Priority'
> -------------------------------

We already have policy sections 2.1.2, 2.1.3, 2.1.4, 2.1.5, and 2.2. I don't
belive the text of section 4.2.9 adds anything that belongs in policy.

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

I have my doubts about this belonging in policy. With package pools we may
well add new distributions, plus this section seems to be intended as a
guide to help people put the right thing in a .changes file.

> 4.2.15. `Urgency'
> -----------------

Disagreed, especially because dinstall doesn't honor this field at all.

> 5. Version numbering
>         All of chapter 5

I agree that this belongs in, with the exception of the first two paragraphs
of that section. (The second paragraph, in particular, is a guide to
understanding how dpkg works and so doesn't belong in policy.)

I also think that the thrid paragrpah of the '<epoch>' section doesn't need
to be in policy. I have my doubts about the fourth paragraph after
'<debian-revision>' needing to be in policy. 

I don't belive any of the part that explains how dpkg compares these numbers
needs to be in policy, except the paragraph about epochs.

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

I agree for most of section 6.1

I disagree that section 6.2 belongs in policy. It is a guide to the way dpkg
works, not something your maintainer scripts can violate, so it doesn't need
to be in policy.

I disagree for all of 6.3, 6.4 and 6.5, for similar reasons.

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

So if this is going to fail anyway before they even have a package built,
why does it need to be in policy? This is a self-correcting problem. :-)

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

See previous paragraph as well for why I dodn't think this needs to be in

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

I disagree, this is another case of documenting how dpkg works, and is not a
case of specifying something a package should or should not do. Thus, it
does not belong in policy.

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

This is once again, just an explination of how dpkg works.

> 8.5.2. Replacing whole packages, forcing their removal

So it this.

> 8.6. Defaults for satisfying dependencies - ordering

So is this.

> 9. Configuration file handling

I think policy 4.7 says enough.

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

I am unsure as well.

see shy jo

Reply to: