Re: New packaging manual draft
I've seen some typos and typographical errors but I won't bother to
detail them at this point.
Each paragraph is a series of fields and values; each field consists
of a name, followed by a colon and the value. It ends at the end of
the line. Horizontal whitespace (spaces and tabs) may occur before or
after the value and is ignored there; it is conventional to put a
single space after the colon.
Is the space before the colon truely optional? I expect there's some broken
code out there if so. RFC 822 does allow it. I think you should point to that
RFC in that section BTW, even though control file format varies from it in
several ways.
They must be at least two characters and must start with an
alphanumeric.
For clarity, use:
"They must be at least two characters long and must start with an
alphanumeric character."
The list of distributions values and their descriptions seem out of place.
In several places it seems to be talking to the end user.
Furthermore, this is quite false these days:
"There is currently no distinction between stable
and unstable packages in the _contrib_ or _non-free_ distributions."
And if non-free and contrib are distributions, the word is being used in a
very different sense than when we apply to to unstable and stable. contrib and
non-free should not be in this list. Note also that the policy manual calls
non-free, main, and contrib "sections" now (and calls Sections subsections,
<sigh>), so the text should be made to agree with that.
Oh yeah, the timeframes (4 month release cycle, 4 week freezes) in this text
are ludicrously optimistic. Just another indication, I think, that the text in
the distribution list descriptions doesn't belong in policy at all.
In the section on version numbers, it says about the epoch,
"This is a single unsigned integer, which should usually be small."
Given that in the introduction, we are told that use of "should" allows filing
of a bug on something. So what is a maintainer to do if some rules lawyer
files a bug "your package has an epoch that is too large"? :-) Suggested fix:
s/should/is/. (My real point here is that taking a manual that used
terms like "should" and "may", formalizing it, and defining those terms
may yeild unexpected behavior.)
If you need to compare version numbers in a script, you may use
`dpkg --compare-versions ...'. Type `dpkg --help' for details on
arguments.
This doesn't belong in policy; I've always read it as just a helpful
hint to maintainers. I think it should be moved into a footnote somehow.
"The clean target mustmay" -- I think you want may?
In the section on changelogs, when it shows the format, the asterisks
are not indented, while it later says they must be indented by 2 spaces.
Also, the "--" line looks indented wrong (in w3m anyway).
The first two paragraphs of section 4.7.1 seem redundant given that the
precise format of the control file as already been specified. They're
useful to maintainers, but should not be part of policy. Similarly for
paragraph 6, except its last sentance.
I think there should be something in here more clearly defining what the
summary is that what the extended description is. The last paragraph
alludes to it, but I see new developers get this wrong all the time.
Section 5.2 sure deals with a lot more sujects than its title would lead
you to believe. It's also amusing that I have seen no package that uses
/dev/tty as the second paragraph of this section describes.
While section 5.4 is of course very useful and important information, I
question the value of including it in policy. For example, it includes
this text:
This is the point of no return - if `dpkg' gets this far, it
won't back off past this point if an error occurs. This will
leave the package in a fairly bad state, which will require a
successful reinstallation to clear up, but it's when `dpkg'
starts doing things that are irreversible.
If someone decides to go make dpkg even more robust, and deal with problems
after that point and manage to back off after that point, it would be
technically in violation of policy. I see no reason to put such a damper
on future progress.
I have similar problems with parts of sections 5.5 and 5.6.
Ok, I lost steam here, will continue later.
--
see shy jo
Reply to: