Dear all,
I just printed out a copy of the latest version of policy (3.5.1.0),
and began to read through it. The first thing that struck me is that
it is a work that has accumulated through a number of patches over a
number of years, and is now quite a disorganised collection of ideas
scattered somewhat randomly over the entire document.
I intend to reorganise the document into a more manageable structure;
for example, all of the control file information should probably be
found together, not scattered across several unrelated chapters.
As a first step towards this, though, I am carefully reading through
the current version, and improving wording and grammar without
introducing changes of meaning. However, there are a few paragraphs I
would like to change, and would like people's comments before I do
so. So far, I have worked through chapters 1 and 2, so here goes.
1.1 Comparison of must, should, may with bug severities: at present,
the text matches "important" with "must" or "required" and
"normal" with "should" or "recommended". But now the bug
severities have changed; there is a new "serious" severity, so
where does that fit in to the general scheme?
2.1 The aims of this policy are....
Is this really the case? Surely this is the aim of Debian
itself, not of the technical policy? The aim of the policy is
primarily to ensure a high technical quality and very high levels
of software interoperability, including ease of installation,
upgrading and use of the system.
Can we somewhat rewrite this bit?
2.1.1 DFSG
This refers at one point to "The Debian group". Should this not
say "The Debian project"?
2.1.3 The contrib section
The paragraph does not actually define the contrib section or
distinguish it from the main section clearly. I propose to
insert the following text, which follows accepted practice and
matches the previous subsection:
Packages in contrib and non-US/contrib
- must comply with the DFSG
- must not be so buggy that we refuse to support them, and
- must meet all policy requirements presented in this manual.
Furthermore, packages in contrib must not require a package in
non-US for compilation or execution.
Examples of packages ....
2.1.4 The non-free section
It would be nice to clarify this. Can we add the following:
Packages in non-free or non-US/non-free must meet all policy
requirements presented in this manual.
(It does not necessarily make sense to talk about buggy, as we
may well not have the source code to fix them.)
Would we have to exclude certain policy requirements for non-free
packages? I would tend to think not, but I may have overlooked
some.
2.2 Priorities
According to the text, the priority levels are recognised by
dpkg. But AFAIK, this is not true; they are only recognised by
higher level software such as dselect and apt. Comments?
2.2 Priorities: important
The text says:
Important programs, including those which one would expect to
find on any Unix-like system. If the expectation is that an
experienced Unix person who found it missing would say `What the
F*!@<+ is going on, where is `foo'', it must be in `important'.
This is an important criterion because we are trying to produce,
amongst other things, a free Unix. ...
Two questions:
(i) Should we write the sentence "If the expectation..." in a
slightly more formal way?!
(ii) Is the sentence "This is an important criterion..." relevant
to the policy document? It's a project goal, not a
technical policy, surely?
2.3.1 The package name
Add: The package name must be at least two characters long and
must not consist solely of digits.
Rationale: two chars long is enforced by the packaging tools.
Solely of digits would confuse the BTS.
2.3.4 Dependencies
This will be merged with the other dependencies sections
currently floating around.
2.3.6 Base packages
There was some discussion about this a while ago. Since the
current definition of base packages are "those packages which the
boot-floppies team put in the base system", is there any meaning
to this section any longer? Should the base section be scrapped?
There are 86 packages currently marked as base; most of them
would make sense elsewhere.
2.3.8 Maintainer scripts
This is a bizarre mish-mash of thoughts, and should really be
merged with the other material on maintainer scripts later in the
current policy document.
Stuff like the comment on dpkg-divert doesn't really belong here;
there should be a separate section on miscellany like this.
2.4.4 Documenting your changes
dpkg does actually support other formats besides the standard
one. This paragraph sort of implies that, but it's not very
clear. Perhaps this should be clarified somewhat:
Current wording:
In non-experimental packages you must only use a format for
`debian/changelog' which is supported by the most recent released
version of `dpkg'. If your format is not supported and there is
general support for it you should contact the `dpkg' maintainer to
have the parser script for your format included in the `dpkg' package.
(You will need to agree that the parser and its manpage may be
distributed under the GNU GPL, just as the rest of `dpkg' is.)
Suggested wording:
In non-experimental packages you must use a format for
`debian/changelog' which is supported by the most recent released
version of `dpkg'.
footnote: If you wish to use an alternative format, you may do
so as long as you include a parser for it in your source
package. The parser must have an API compatible with that
expected by dpkg-genchanges and dpkg-gencontrol. If there is
general interest in the new format, you should contact the
`dpkg' maintainer to
have the parser script for it included in the `dpkg' package.
(You will need to agree that the parser and its manpage may be
distributed under the GNU GPL, just as the rest of `dpkg' is.)
Rationale for this new wording:
(1) The current wording is confusing, as most people are unaware
of the possibility of alternative formats.
(2) The footnote does not actually conflict with the main text,
as if the parser is provided, then the format is actually
supported by dpkg!
2.4.6 Obsolete contructs and libraries
Is this relevant to policy any more? It is impossible to compile
against libtermcap any longer, as the files do not exist. It is
still possible, though, to use varargs.h. But these appear to be
two randomly selected examples of software which has been
superceded. Maybe there should be an appendix with such
information, but it's not so useful unless it's kept up to date.
That's all of my significant comments on chapters 1 and 2.
Julian
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Julian Gilbey, Dept of Maths, Queen Mary, Univ. of London
Debian GNU/Linux Developer, see http://people.debian.org/~jdg
Donate free food to the world's hungry: see http://www.thehungersite.com/
