Re: The case for rewriting the Policy document (Debconf7 proposal)
Manoj Srivastava wrote:
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.
I still have the question: policy of what?
.deb packages or Debian in general?
To be clear: ok to include menu, perl, python,... policies,
but I don't want to merge NM, machines, ... policies
It will be only for debian or we mark debian specific
stuff (contrib/non-free, distribution names, security contacts,...) ?
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.
hmm. If the structure of document is clear, I don't think it would
difficult to have only one single document.
User will usually (??) use policy from an electronic version
(cross-links), so we need only to generate a different content page.
And about numeration? Policy 2.6.3 (an example) should be
about the same topic in all the documents, but user should also
easy to find in every kind of documentation (ordered? cross links?).
So I don't think we should "publish" different structured versions.
But I agree to publish reduces version (only MUST, without rationale,
without specific topic,...)
I propose as alternative: every policy statement should have a
summary line i.e.
"12.34.5 - MUST: init.d scripts should be POSIX shell scripts",
and than we distribute this one liner (or 3 lines or whatever) according
different priorities, topics, ...
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).
as POSIX man pages. With ev. "future direction" and "best practices".
(maybe included only on the full version).
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.
It is ok, but we should use only a small subset of docbook.
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.
Ok, if the content is almost text and not format.
Comments welcome.
ciao
cate
Reply to: