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

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

        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

        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

        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.

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: