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. [...]
Comments:
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
relocated.)
6. "`Section' The `section' of the package, as shown and used
by `dselect', and used as a location for this package in the
distribution."
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
appropriate.
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
how.
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: