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

Re: New packaging guidelines - draft

Ian Jackson <ian@chiark.chu.cam.ac.uk> said:

> Below is a draft copy of a revised set of packaging guidelines.
> Please comment if you feel appropriate. [...]


1.  "Text documentation should be [...] installed in /usr/doc."

    This is wrong.  Text documentation should be installed in
    /usr/doc/<package>.  /usr/doc got so cluttered that it was
    decided to require packages to use individual subdirectories.

2.  "If a subdirectory of /usr/doc is warrented, please create one."

    This should be strengthened, I think.  Packages should install no
    plain files in /usr/doc.  Packages may install subdirectories
    /usr/doc/<package> and /usr/doc/examples/<package> and place
    items in those subdirectories.

3.  "include a description of your changes in the `debian.README'
    (which, as described above, [...]"

    However, debian.README has not been described above.

4.  "`Description'    The description of the package"

    This needs to explain about the extended description field,
    its formtting requirements, how strongly it's suggested, and
    its desired content (some packages have been criticised after
    uploading on the basis of extended description content.  If
    such criticism is to be forthcoming, guidelines for avoiding
    it should be provided.).

5.  "`Essential' a boolean field used by the base packages"

    Should provide info on the required contents to indicate
    the boolean values True and False.

    (wait a minute.  I now see that this information is provided,
    but it's provided five pages later.  Perhaps the information be

6.  "`Section'  The `section' of the package, as shown and used
    by `dselect', and used as a location for this package in the

   I think we decided that this is no more than a suggestion by the
   package maintainer, and that the central distribution maintainer
   may decide, without consultation with the package maintainer, to
   place the package elsewhere than in the location described by this
   field.  I also believe that we decided that when this is done,
   the (now erronious and misleading) `Selection' field provided
   by the package maintainer will be retained.  The central distribution
   maintainer is not under any requirement to notify the package
   maintainer of this situation.

   (I note that this field is re-discussed several pages onward, under
   "Priority, Section, and Essential".  Rather than being discussed
   partway in each of two places, perhaps these fields should be
   discussed only in one place.  If they're mentioned in more than
   one place, a pointer can be provided where they're mentioned to the
   place where they're discussed.)

7.  "If your maintainer scripts need to prompt for passwords and/or do
    full-screen interaction should do these things [...]"
                           +-- missing words?

8.  "and they should ensure that the user will only every be asked [...]"

9.  "If these scripts exist they shouuld be left in the `DEBIAN'
    directory [...]"

    This sounds as if we've suddenly shifted gears from talking about
    files and directory locations on the target system to files and
    directory locations in the package being constructed.  This section
    seems to be speaking to the situation where a package maintainer has
    taken over responsibility for a pre-existing package and has
    found a DEBIAN directory in the source package.  This needs
    more foundation.

10. "The `Conflicts' field lists packages that conflict with this one,
    for example by containing files with the same names. [...]"

    However, this is not an absolute, and this should be explained.
    For example:

    elv-fmt and textutils packages, for example, both supply
    /usr/bin/fmt.  It's been determined, however, that these
    packages should be allowed to overwrite this file from whichever
    package happened to be installed last without specifying a
    conflict with one another.  Such special cases should be
    explained in the packaging guidelines, and guidelines should be
    provided for when, what, and why special-case handling is

    The various vi clones use a rather baroque "update-alternatives"
    mechanism, which needs to be mentioned here with a pointer to
    the documentation.

11.  A pointer to the document describing legal virtual package names,
     their menaings, and the procedure for establishing and advertising
     a new virtual package name should be provided.

12.  "Priority, Section and Essential [...] "you should be sure you keep
     this information up to date [...].

     This implies an assumption that package installers will always
     be working from a matched set of the most up to date packages.
     That assumption won't always be satisfied.

     This isn't the forum for this, but I have doubts that these fields
     have the intended impact in scenarios which don't have net-connected
     users working from the online distribution.  For example, it seems
     to me that problems with these fields (and more serious other problems)
     can easily occur if users try to install outdated packages from
     old-vintage CDROM distribution copies after having installed
     packages from a later vintage.  One example of a situation where
     such a problem can occur is in the corrently contemplated removal
     of the /etc/init.d/functions script from the sysvinit package,
     followed by attempted installation of a package from an older CDROM
     which expects that script to be in place.

13.  The /etc/init.d and /etc/rc.boot directories need to be explained.
     Package maintainers need to know what goes there, when, why, and

14.  The install-info, update-alternatives, start-stop-daemon, and any
     other debian-specific and packaging related scripts and programs
     which might be invoked from package scripts need to be explained,
     and pointers to their documentation needs to be provided.
     Package maintainers need to know when, why, and how to use these
     scripts and programs.

Reply to: