Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)

[Guillem Jover]

Hi!

On Sat, 2022-12-17 at 17:24:57 -0700, Sean Whitton wrote:
> On Sat 17 Dec 2022 at 04:43PM +01, Guillem Jover wrote:
> > Sorry, probably my fault! As I tend to use «Fixes:» git pseudo-fields
> > for things that fix part of a bug, but are not intended yet to close it,
> > for which I use «Closes:».
> >
> > And for some reason I think I also got the impression, even though
> > the stanza changes had been committed, they could still be backed out.
> > (BTW I've now gone over the wiki and updated all paragraph references
> > that applied to stanza.)
> >
> > In any case, I've sat down and gone over the meat of the original
> > report. See below.
>·
> We're sticking with 'stanza', and in light of that, could you confirm
> that the bug is reopened in order to make additional fixes, rather than
> back anything else out?

In case my other replies to Russ didn't make this clear. This comment
was in reference to the various replies in the sub-thread started by
Charles, where it looked to me like whether to back that out was still
an open question for the editors.

In any case, as I mentioned, given the changes being included in the
release, I took that as indeed, sticking with the term, and that's why
I reopened and submitted the actual changes this original report was
intending on requesting. :)

As an aside I've since updated the dpkg code and docs to refer to
these as stanzas everywhere applicable.

Thanks,
Guillem

Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)

[Sean Whitton]

Hello,

On Sat 17 Dec 2022 at 04:43PM +01, Guillem Jover wrote:

> Control: reopen -1
>
> Hi!
>
> Sorry, probably my fault! As I tend to use «Fixes:» git pseudo-fields
> for things that fix part of a bug, but are not intended yet to close it,
> for which I use «Closes:».
>
> And for some reason I think I also got the impression, even though
> the stanza changes had been committed, they could still be backed out.
> (BTW I've now gone over the wiki and updated all paragraph references
> that applied to stanza.)
>
> In any case, I've sat down and gone over the meat of the original
> report. See below.

We're sticking with 'stanza', and in light of that, could you confirm
that the bug is reopened in order to make additional fixes, rather than
back anything else out?

Thanks.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)

[Guillem Jover]

On Sat, 2022-12-17 at 08:35:02 -0800, Russ Allbery wrote:
> (That said, and this is only personal preference and I don't feel that
> strongly about it, I usually err on the side of creating lots of bugs so
> that there can be roughly one bug per patch.  It can make it a bit harder
> to track things if there's one bug following a bunch of semi-related but
> separable changes.  Unfortunately, the BTS doesn't support the concept of
> a hierarchy with a tracking issue and a bunch of underlying implementaton
> issue very well.)

(Right, personally I don't think I'd split one bug per patch, as long
as the patch is covering the same thing, perhaps. In this case I
pondered about opening a new one, but given the initial discussion
and context was here it seemed best to keep it together. Should have
perhaps split the stanza stuff into another report, though. :)

(In any case, hope this is all not too inconvenient!)

> Guillem Jover  writes:
> > And for some reason I think I also got the impression, even though
> > the stanza changes had been committed, they could still be backed out.
> > (BTW I've now gone over the wiki and updated all paragraph references
> > that applied to stanza.)
> 
> I'm personally happy to stick with stanza.

Sorry, rereading that paragraph it seems not clear on what I was
trying to convey. :) I meant that because I thought this could be backed
out until an upload, I guess subconsciously postponed further changes
for this (both in dpkg and here) based on that. Should have asked.

> > I also recalled another term that has always seemed very confusing in
> > context: «control information files» or «control information area». For
> > example in a sentence such as “the control file is a control information
> > file in the control information area in a .deb archive”. :) This also
> > seems confusing when some of the files in the .deb control member are
> > not really “control files” with a deb822(5) format.
> 
> > My thinking has been going into calling these as the «metadata files»,
> > and being located in either the  «metadata part of the .deb archive» or
> > explicitly the «control member of the .deb archive», in contrast to the
> > filesystem part. In dpkg I'd be eventually switching to meta/metadata
> > and fsys/filesystem, from control or info and data. I've added a patch
> > with the proposed change, but again nothing set in stone, and I'm again
> > open to discussing pros/cons of this.
> 
> I like metadata file, but I think I prefer talking about the "control
> member" than the "metadata part" because it more closely matches what one
> sees if one takes the *.deb file apart.  But I haven't looked at your
> diffs yet.

Probably more clear currently, yeah. To expand on the above, my thinking
has been for example that if we ever have a deb 3.0 format, I'd probably
like to name the members, something like: «meta.tar.*» and «fsys.tar.*»,
and that's also what I've kind of been moving the dpkg internals to
(functions, structs and similar). Also as part of the file metadata work,
I've also have pending splitting the dpkg db info/ dir into a dir that
contains things shipped by the .deb, and a dir for stuff generated by
dpkg itself, so that they cannot conflict or get overwritten or need
to be taken into account doing any of that.

Thanks,
Guillem

Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)

[Russ Allbery]

Guillem Jover  writes:

> Sorry, probably my fault! As I tend to use «Fixes:» git pseudo-fields
> for things that fix part of a bug, but are not intended yet to close it,
> for which I use «Closes:».

Ack, sorry, this was my fault.  I optimistically added a bug closer when I
started merging patches from this bug in the hope that we'd get them all
merged before the next release and then forgot about it.

(That said, and this is only personal preference and I don't feel that
strongly about it, I usually err on the side of creating lots of bugs so
that there can be roughly one bug per patch.  It can make it a bit harder
to track things if there's one bug following a bunch of semi-related but
separable changes.  Unfortunately, the BTS doesn't support the concept of
a hierarchy with a tracking issue and a bunch of underlying implementaton
issue very well.)

> And for some reason I think I also got the impression, even though
> the stanza changes had been committed, they could still be backed out.
> (BTW I've now gone over the wiki and updated all paragraph references
> that applied to stanza.)

I'm personally happy to stick with stanza.

> I also recalled another term that has always seemed very confusing in
> context: «control information files» or «control information area». For
> example in a sentence such as “the control file is a control information
> file in the control information area in a .deb archive”. :) This also
> seems confusing when some of the files in the .deb control member are
> not really “control files” with a deb822(5) format.

> My thinking has been going into calling these as the «metadata files»,
> and being located in either the  «metadata part of the .deb archive» or
> explicitly the «control member of the .deb archive», in contrast to the
> filesystem part. In dpkg I'd be eventually switching to meta/metadata
> and fsys/filesystem, from control or info and data. I've added a patch
> with the proposed change, but again nothing set in stone, and I'm again
> open to discussing pros/cons of this.

I like metadata file, but I think I prefer talking about the "control
member" than the "metadata part" because it more closely matches what one
sees if one takes the *.deb file apart.  But I haven't looked at your
diffs yet.

> Attached the proposals for discussion/review, and I might again have
> perhaps missed instances or similar.

Will take a look soon!

-- 
Russ Allbery (r...@debian.org)  

Bug#1020248: marked as done (debian-policy: Clarifying nomenclature for control file names)

[Guillem Jover]

Control: reopen -1

Hi!

Sorry, probably my fault! As I tend to use «Fixes:» git pseudo-fields
for things that fix part of a bug, but are not intended yet to close it,
for which I use «Closes:».

And for some reason I think I also got the impression, even though
the stanza changes had been committed, they could still be backed out.
(BTW I've now gone over the wiki and updated all paragraph references
that applied to stanza.)

In any case, I've sat down and gone over the meat of the original
report. See below.

On Sat, 2022-12-17 at 03:09:10 +, Debian Bug Tracking System wrote:
> Date: Sun, 18 Sep 2022 22:28:00 +0200
> From: Guillem Jover 
> To: sub...@bugs.debian.org
> Subject: debian-policy: Clarifying nomenclature for control file names
> 
> Package: debian-policy
> Version: 4.6.1.1
> Severity: wishlist

> This is a followup from my comment at:
> https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=998165#43
> 
> To summarize, we have IMO confusing naming and nomenclature for the
> various control files and paragraphs/stanzas, and this is even
> confusing me when having to deal with dpkg code, so I'd like to give
> these more clear and unambiguous new names, and I'd very strongly
> prefer to agree on the same naming for Debian policy and dpkg, to
> avoid further and worse confusion (even though they currently do not
> match exactly anyway, but I'd prefer to not make it worse…).
> 
> Just for reference and to give some context, I've got the following
> WIP branches, trying to clarify the names in documentation and in the
> API on, which I'll probably rework (split/merge) and reword as needed,
> so do not take them as anything set in stone:
> 
>   
> https://git.hadrons.org/git/debian/dpkg/dpkg.git/log/?h=next/clarify-control-filenames
>   
> https://git.hadrons.org/git/debian/dpkg/dpkg.git/log/?h=next/deb822-field-types
> 
> 
> File descriptions
> -
> 
> For example we have:
> 
>   * debian/control:
> policy → «Source package control file»
> dpkg   → «Debian source packages' master control file»
> 
>   * .dsc:
> policy → «Debian source control file»
> dpkg   → «Debian source packages' control file»
> 
>   * DEBIAN/control
> policy → «Binary package control files»
> dpkg   → «Debian binary packages' master control file»

Seems I missed another file:

  * .changes:
policy → «upload control file» / «Debian changes file»
dpkg   → «upload control file» / «.changes control file» /
 «Debian .changes file» / «Debian changes file»

> These are quite confusingly close.
> 
> I've been considering naming debian/control something like
> «Debian template source package control file», as that is used to
> generate both the source and binary control files. And always
> prefixing with Debian, so that would end up as:
> 
>   * debian/control: «Debian source package template control file»
>   * .dsc:   «Debian source package control file»
>   * DEBIAN/control: «Debian binary package control file»

For changes I think something like the following might be a more clear
option (and has the minor bonus of aligning perfectly on the first
words! :), with it mentioning explicitly this is about changes being
uploaded, and that it is a control file (but I'm not sure I'm entirely
convinced about it):

* .changes:   «Debian upload changes control files»

> This also removes the «master» usage in dpkg, for me for the same
> reasons as I covered at
> .

> File contents
> -
> 
> We have references to the various parts being called as «paragraphs»,
> «stanza», «blocks», but this seems to be more of an issue with dpkg, as
> the usage in the Debian policy is quite clear and uniform now, so I'll
> at least try to remove the «block» usage there, stanza has the nice
> property of being shorter and policy already mentions that this is
> currently a common alias, so I might keep paragraph and stanza for now
> in dpkg.

I've also found instances of «record» and «section» referring to fields
or stanzas.

> The other thing affecting dpkg and debian-policy is how the parts
> within the control files are referred to. We have for example:
> 
>   dpkg   → «general section of control info file»
>«source stanza»
>   policy → «general paragraph»
> 
>   dpkg   → «package's section of control info file»
>   policy → «binary package paragraphs»
> 
> 
> So, how does «source package paragraph» and «binary package paragraph»
> (of the «template control file») sound instead?

> If I've missed any other problematic nomenclature, I'm happy to
> discuss and update those on the dpkg side.

I also recalled another term that has always seemed very confusing in
context: «control information files» or «control information area». For
example in a sentence such as “the control file is a control information
file in the control information area in a .deb archive”. :) This also
seems confusing when some of the files