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

Bug#72949: PROPOSED] 00/10/02 Policy aspects of the packaging manual



On Mon, Oct 02, 2000 at 12:06:13AM -0500, Manoj Srivastava wrote:
> Package: Debian-policy
> Version: 3.2.1.0
> Severity: wishlist
> 
>           I propose that the following file be included in policy, and
>  be referenced in the Policy manual. Subsequently the packagign manual
>  package can be taken over by the developers maintaining the Debian
>  package management system.
> 
> 	I am now looking for seconds for this proposal.

[Hi!  I'm sort of beginning to get my head out from under the water
again, although I will be around rather sporadically for the next few
weeks still.]

I second it, but have a few specific comments to make.

Firstly, well done!

Secondly, I think it would be nicer to actually integrate it into the
policy document itself.  More work initially, I agree, but it reduces
the number of documents to be consulted, and also the number of
distinct documents which require maintenance.  This is especially the
case given that a significant amount of policy already discusses
packaging issues.

There are some little spelling/grammar issues, which I can always fix
up later, so I won't detail them here.

Next, the copyright statement on lines 8--12 is inconsistent with
that which appears later on.

The paragraph beginning on line 156 (New versions of this document)
will need to be corrected to point to the correct location of this
document wherever it ends up.

The paragraph beginning at line 273, referring to package names:

	    They must be at least two characters long and must start
	    with an alphanumeric character.  The use lowercase package
	    names is strongly recommended unless the package you're
	    building (or referring to, in other fields) is already
	    using uppercase.</p>

I thought we lowercase the name whatever?  In potato, there is not a
single package with any uppercase characters in the name.

Paragraph beginning line 303, describing Standards-Version:

	    Its format is the same as that of a version number except
	    that no epoch or Debian revision is allowed - see <ref
	    id="versions">.</p>

This isn't really correct; it has a much more restricted format, as
described in the Policy manual.  (majorX.majorY.minorX[.minorY], all
of which are numbers.)

The Distributions section needs lines 373-397 (</taglist>), describing
contrib and non-free, removing, as this has nothing to do with the
value of the "Distribution" field.

Should the "unusual circumstances" described in the footnote there
(line 398) be elucidated?  I don't remember off-hand where
descriptions of bug fixes for stable and frozen are found, but it
would make sense to refer to that doc.

I think that things would be a little clearer if we modified the end
of the para 418-426 (version numbering) to say:

-	the one installed on the system.  The version number format
-	has the most significant parts (as far as comparison is
-	concerned) at the beginning.
+	the one installed on the system.  The version number format
+	has three components, <var>epoch</var>,
+	<var>upstream-version</var> and <var>debian-revision</var>,
+	with <var>epoch</var> the most significant component and
+	<var>debian-revision</var> the least significant component
+	(as far as comparison is concerned).

Line 430 should read (it's currently garbled):
	&lsqb<var>epoch</var><tt>:</tt>&rsqb;<var>upstream-version</var>&lsqb;<tt>-</tt><var>debian-revision</var>&rsqb;

Lines 488-492 concerning the debian-revision should be rewritten as
follows (and the paragraph lines 521-525 consequently removed); it
makes things clearer:

	      This part of the version represents the version of the
	      modifications that were made to the package to make it a
	      Debian binary package.  It may contain only
	      alphanumerics and the characters <tt>+</tt> and
	      <tt>.</tt> (plus and full stop) and should start with a
	      digit.

Lines 539-540, describing the first component of the upstream-version:

-	non-digit characters is determined.  These two parts (one of
-	which may be empty) are compared lexically.  If a difference
+	non-digit characters is determined.  These two parts (either of
+	which may be empty) are compared lexically.  If a difference

Should we change the numerical dates on line 596 to something more
up-to-date?!

Paragraph lines 649-659: this has the nonsensical line: "At a minimum,
required targets are ...".  Required targets must be explicitly
listed.  It would make sense to make the following changes:

	<p>
	  Since an interactive <tt>debian/rules</tt> script makes it
	  impossible to auto-compile that package and also makes it
	  hard for other people to reproduce the same binary
-	  package, all <strong>required targets</strong> MUST be
-	  non-interactive. At a minimum, required targets are the
-	  ones called by <prgn>dpkg-buildpackage</prgn>, namely,
-	  <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
-	  <em>build</em>. It also follows that any target that these
-	  targets depend on must also be non-interactive.
+	  package, all required targets <em>must</em> be
+	  non-interactive and all other targets <em>should</em> be
+	  non-interactive.  It also follows that any target that a
+	  required target depends on <em>must</em> also be
+	  non-interactive.
	</p>
	
	  <p>	    
-	  The targets which must be present are:	    
+	  The required targets, which must be present, are:	    
	  <taglist>

Line 704: don't we encourage touching build-stamp rather than build
nowadays, with "build: build-stamp" and "build-stamp:" doing the work?
(See, eg, debhelper examples.)

Lines 753-756, which say that the binary targets must be invoked as
root doesn't really make sense; at the very least, a rationale should
be given and the possibility of using fakeroot should be described.
And it makes sense to append "when building a package" at the end.

There should be a new list which begins before "get-orig-source" for
optional targets in the debian/rules file, to distinguish them from
the first list which is the required targets.

Lines 817-819:

	  The <prgn>build</prgn>, <prgn>binary</prgn> and
	  <prgn>clean</prgn> targets must be invoked with a current
	  directory of the package's top-level directory.

I know what it's trying to say, but I'm not sure it quite does it.
Maybe the following would be better:

	  The required and optional targets <em>must</em> assume that
	  they are invoked with the current directory being the
	  package's top-level directory, unless otherwise stated.

And if so, then it should probably go before the list of targets.

Lines 934ff, describing changelog entries:

	  The change details may in fact be any series of lines
	  starting with at least two spaces, but conventionally each
	  change starts with an asterisk and a separating space and
	  ...

I would change the last line to:

	  change starts with two spaces, an asterisk and
	  a separating space, and ...

just to be explicit.

Lines 959-961, describing the date format in changelogs:

	  </footnote>; it should include the time zone specified
	  numerically, with the time zone name or abbreviation
	  optionally present as a comment.

I would remove the words "as a comment", as they are confusing.  (How
do you introduce a "comment" in a changelog terminating line?)

The section beginning line 972 on defining an alternative changelog
format is incomplete: it does not say how to do it or what is required
of a format.  Somewhere this should be specified, perhaps in an
appendix to the policy document.  I could probably write it, as long
as someone like Wichert or one of the other dpkg developers is
prepared to check it.

I've run out of steam for today.  But that's close to 40% checked
through ;-)

   Julian

-- 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

  Julian Gilbey, Dept of Maths, QMW, Univ. of London. J.D.Gilbey@qmw.ac.uk
        Debian GNU/Linux Developer,  see http://www.debian.org/~jdg
  Donate free food to the world's hungry: see http://www.thehungersite.com/



Reply to: