Bug#547272: Clarification of the Format field in control files
Hi Russ and Emilio,
Le Tue, Jun 22, 2010 at 07:57:03PM +0200, Emilio Pozuelo Monfort a écrit :
> >
> > <p>
> > + <file>.changes</file> files have a format version that is
> > + incremented whenever the documented fields or their meaning
> > + change. This document describes format 1.8.
> > + </p>
> > + In <qref id="debianchangesfiles"><file>.changes</file></qref>
> > + files, this field declares the format version of that file.
> > + The syntax of the field value is the same as that of
> > + a <qref id="f-Version">package version number</qref> except
> > + that no epoch or Debian revision is allowed. The format
> > + described in this document is <tt>1.8</tt>.
> > + </p>
> > +
I wonder if it is a good thing to have the format version number given two
times. How about removing one instance, or adding SGML comments warning that
modification has to be done in two places? Or using a SGML entity?
> In the other paragraph, you say "In .changes files", maybe you should also say
> "In .dsc files" here (or the other way round)?
I also think that it makes the Policy clearer if it uses consistently one
terminology. We have the choice between the short names that is used in most
discussions on the Debian mailing lists (.changes, .dsc, debian/control), and
the longer names that are not much used outside the Policy (Source package
control, Binary package control, Debian source control, and Debian changes
files).
One problem of the short/causal names it that debian/control and DEBIAN/control
are spoken the same (although it would be interesting to distinguish them by
shouting Debian in the second case). Not to mention that “Debian control file”
is (although not in practice) a vague term, since the Policy also sometimes
refer to files like postinst as “control files”.
So despite this does not reflect the practice in electronic communications, I
would recommend to use the more formal long names to refer to the control data
files of source and binary packages.
> Seconded, with and without a change for my comment above.
Same for me. I gave my opinion, but trust your final decision.
Ah, and lastly, here are two minor comments:
> <p>
> - The .changes files are used by the Debian archive maintenance
> - software to process updates to packages. They contain one
> - paragraph which contains information from the
> + The <file>.changes</file> files are used by the Debian archive
> + maintenance software to process updates to packages. They
> + contain one paragraph which contains information from the
> <tt>debian/control</tt> file and other data about the
> source package gathered via <tt>debian/changelog</tt>
> and <tt>debian/rules</tt>.
> </p>
Is there a reason for using a <file> markup for the .changes file, but a <tt>
markup for debian/control, debian/changelog, and debian/rules? Of course, I
understand that being consistent across the whole document is beyond the scope
of this bug.
More cosmetically, if the Debian changes file are always made of one paragraph
only, perhaps we can avoid the repetition of ‘contain’ (‘They contain one
paragraph which contains’) with the following sentence in replacement:
“They consist in a single paragraph which which contains…”
Have a nice day,
--
Charles
Reply to: