The case for rewriting the Policy document (Debconf7 proposal)
Hi folks,
This proposal is based on part of a talk I gave at debconf7, and
is about reorganizing the policy document(s). The current policy
document grew organically from the dpkg documentation, and the
packaging manual, and has grown bloated, and contains material that
does not sanely belong in policy. Policy needs to come closer to
release goals. We really should not need a release team RC criteria
list.
The must/should/may labels are not consistent, or correct (the
separate RC bug listings created by the release managers are a symptom
of this.) This has many ramifications, and bears a cost for the
developers; if the policy is not quite right; policy checking software
can't really be authoritative, and maintainers always have a niggling
doubt about the correctness of policy. While policy may always have
bugs, we can certainly improve on the current situation.
There are far too many policy documents. The main technical
policy, the Perl policy, the MIME policy, the emacs policy, the menu
policy, the python policy .... indeed, I can't come up with an
exhaustive list; which is a problem if I were to create a package
governed by one of the missing policy documents. We need some place
where _all_ the policy manuals that may govern package creation are
listed.
The policy document is organized in a manner that makes it hard
for a maintainer to judge conformance. There are two ways one might
want to read policy; one is by topic: when reviewing a certain area of
packaging, it is useful to see _all_ applicable policy rulings,
regardless of severity levels, and regardless of which document the
rule might be established in; a second way of looking at policy is look
at rules based on how critical it is to conform; in other words, to
look at all the RC rules that are applicable to a package; then to look
at the serious-bug-rules, and then to recommendations, and so on. The
current structure of the policy document(s) does not allow this to
happen. It would be nice to have a one stop shop for all packaging
materials, with decreasing criticality and perhaps increasing size, and
this would definitely make getting into packaging for Debian easier.
Not all the current policy dictums come with a clear rationale,
and nor do they come with a set of suggested checks to be used for
packages (to help out lintian and linda and others). Unfortunately,
long after the discussion that lead to the policy rule is forgotten,
and perhaps after to participants have moved on from Debian, the rules
remain, and lead t much confusion and discussion later. It would be
nice to have a new unit for a policy rule; firstly, the normative rule
itself, accompanied with an informative rationale, and perhaps
examples; and optionally, a language neutral lintian/linda check (more
on this in another mail).
I propose that we start creating a new set of policy manuals,
using Docbook instead of Debiandoc. Docbook is popular, well
maintained, allows indices and cross references, and has many rendering
formats.
Each policy rule can be an XML/SGML entity; and have clearly
defined the severity (MUST/SHOULD/MAY); the _topic_ it belongs to; the
normative part, the rationale, and the check.
We can then create outer manuals, that just provide the matrix
for these XML/SGML entities, and we can have several such container
manuals, which can slice and dice the entities in different ways
(organize by severity; organize by topic, with multiple topic orderings
possible). Doing entity based manuals have an advantage that
derivatives and sub distributions can easily add on to the policy
manual and derive from it as well.
A multi-part book allows the creation of a comprehensive book
from different documents with differing inclusion and editing criteria
(in other words, we can have a comprehensive multi-part book that
starts with the technical policy manual and ends with the developers
reference, with every other policy document in between).
The new document can be built up with a clear convention for
normative rule, informative rationale, and optional package checking
pseudo code. It would also be easily reorganized for flow. The policy
rules can come under a long overdue review, and consistent editorial
practice would benefit readability. This is the time to perform cruft
removal, add indices, and cross references. Some material should
certainly move to the developers reference, and perhaps some material
needs to migrate the other way.
Also, the copyright and license on the current policy manual is
murky; we can settle on the GPL as the copyright of the new manual, and
add on to the lsit of contributors/copyright holders from the get go.
This is a several years old bug on the policy manual.
Comments welcome.
manoj
--
If all else fails, immortality can always be assured by spectacular
error. John Kenneth Galbraith
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: