Bug#881431: proposed wording

[Holger Levsen]

On Wed, Apr 04, 2018 at 11:47:09AM -0700, Sean Whitton wrote:
> > §3.2.2 Uniqueness of version numbers
> >
> > The part of the version number after the epoch must not be reused for
> > a version of the package with different contents once the package has
> > been accepted into the archive, even if the version of the package
> > previously using that part of the version number is no longer present
> > in any archive suites.
> >
> > This uniqueness requirement applies to the version numbers of source
> > packages and of binary packages, even if the source package producing
> > a given binary package changes.  Thus the version numbers which a
> > binary package must not reuse includes the version numbers of any
> > versions of the binary package ever accepted into the archive, under
> > any source package.
> >
> > Additionally, for non-native packages, the upstream version must not
> > be reused for different upstream source code, so that for each source
> > package name and upstream version number there exists exactly one
> > original source archive contents [reference to defintiion of that].
> >
> > The reason for these restrictions is as follows.  Epochs are not
> > included in the names of the files that compose source packages, or in
> > the filenames of binary packages, so reusing a version number, even if
> > the epoch differs, results in identically named files with different
> > contents.  This can cause various problems.
> >
> > If you find yourself wanting to reuse the part of a version number
> > after the epoch, you can just increment the Debian revision, which
> > doesn't need to start at 1 or be consecutive.

seconded, thanks.


-- 
cheers,
Holger


signature.asc
Description: PGP signature

Bug#881431: proposed wording

[Simon McVittie]

On Wed, 04 Apr 2018 at 11:47:09 -0700, Sean Whitton wrote:
> > §3.2.2 Uniqueness of version numbers
> >
> > The part of the version number after the epoch must not be reused for
> > a version of the package with different contents once the package has
> > been accepted into the archive, even if the version of the package
> > previously using that part of the version number is no longer present
> > in any archive suites.
> >
> > This uniqueness requirement applies to the version numbers of source
> > packages and of binary packages, even if the source package producing
> > a given binary package changes.  Thus the version numbers which a
> > binary package must not reuse includes the version numbers of any
> > versions of the binary package ever accepted into the archive, under
> > any source package.
> >
> > Additionally, for non-native packages, the upstream version must not
> > be reused for different upstream source code, so that for each source
> > package name and upstream version number there exists exactly one
> > original source archive contents [reference to defintiion of that].
> >
> > The reason for these restrictions is as follows.  Epochs are not
> > included in the names of the files that compose source packages, or in
> > the filenames of binary packages, so reusing a version number, even if
> > the epoch differs, results in identically named files with different
> > contents.  This can cause various problems.
> >
> > If you find yourself wanting to reuse the part of a version number
> > after the epoch, you can just increment the Debian revision, which
> > doesn't need to start at 1 or be consecutive.

Seconded, thanks.

Bug#881431: proposed wording

[Sean Whitton]

Hello,

Thank you for the feedback, Simon.

I tried to incorporate what you said while avoiding talking about the
namespace pairs, for the sake of readability.  Further, I shortened
"upstream version without the epoch" to "upstream version" because the
epoch is a Debian thing.

Seeking seconds:

> §3.2.2 Uniqueness of version numbers
>
> The part of the version number after the epoch must not be reused for
> a version of the package with different contents once the package has
> been accepted into the archive, even if the version of the package
> previously using that part of the version number is no longer present
> in any archive suites.
>
> This uniqueness requirement applies to the version numbers of source
> packages and of binary packages, even if the source package producing
> a given binary package changes.  Thus the version numbers which a
> binary package must not reuse includes the version numbers of any
> versions of the binary package ever accepted into the archive, under
> any source package.
>
> Additionally, for non-native packages, the upstream version must not
> be reused for different upstream source code, so that for each source
> package name and upstream version number there exists exactly one
> original source archive contents [reference to defintiion of that].
>
> The reason for these restrictions is as follows.  Epochs are not
> included in the names of the files that compose source packages, or in
> the filenames of binary packages, so reusing a version number, even if
> the epoch differs, results in identically named files with different
> contents.  This can cause various problems.
>
> If you find yourself wanting to reuse the part of a version number
> after the epoch, you can just increment the Debian revision, which
> doesn't need to start at 1 or be consecutive.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#881431: proposed wording

[Simon McVittie]

On Thu, 29 Mar 2018 at 08:12:15 -0700, Sean Whitton wrote:
> Seeking seconds:
> 
> > §3.2.2 Uniqueness of version numbers

This has lost the part of Adam's wording where he explicitly said that
this applies to all three of these namespaces:

* (source package name, source version without epoch)
* (binary package name, binary version without epoch)
* (non-native source package name, upstream version without epoch or
  Debian revision)

and I think that's valuable information.

Perhaps adding a paragraph like this would address that?

"""
This uniqueness requirement applies to source package names and versions,
and to binary package names and versions (even if the binary package was
previously produced by a different source package). Additionally, for
non-native packages, the upstream version without the epoch (excluding
the Debian revision) must not be reused for different content, so that
each (source package name, upstream version without epoch) pair refers
to the same original source archive (see _Source packages as archives_).
"""

(This could be interpreted as either allowing or forbidding replacement of
foo_1.2.3.orig.tar.gz with foo_1.2.3.orig.tar.xz if they uncompress
to the same foo_1.2.3.orig.tar, or even to an equivalent but not
byte-identical foo_1.2.3.orig.tar - I'd be tempted to say that's silly
and should not be allowed either, but I'm not sure how to make that more
explicit.)

> > If you find yourself wanting to reuse the part of a version number
> > after the epoch, you can just bump the Debian revision, which doesn't
> > need to start at 1 or be consecutive.

"increase the Debian revision" might be clearer and is certainly more
formal.

smcv

Bug#881431: proposed wording

[Holger Levsen]

On Thu, Mar 29, 2018 at 08:12:15AM -0700, Sean Whitton wrote:
> Seeking seconds:
> 
> > §3.2.2 Uniqueness of version numbers
> >
> > The part of the version number after the epoch must not be reused for
> > a version of the package with different contents once the package has
> > been accepted into the archive, even if the version of the package
> > previously using that part of the version number is no longer present
> > in any archive suites.
> >
> > Epochs are not included in the names of the files that compose source
> > packages, or in the filenames of binary packages, so reusing a version
> > number, even if the epoch differs, results in identically named files
> > with different contents.  This can cause various problems.
> >
> > If you find yourself wanting to reuse the part of a version number
> > after the epoch, you can just bump the Debian revision, which doesn't
> > need to start at 1 or be consecutive.
 
seconded, thanks.


-- 
cheers,
Holger


signature.asc
Description: PGP signature

Bug#881431: proposed wording

[Sean Whitton]

Hello,

Seeking seconds:

> §3.2.2 Uniqueness of version numbers
>
> The part of the version number after the epoch must not be reused for
> a version of the package with different contents once the package has
> been accepted into the archive, even if the version of the package
> previously using that part of the version number is no longer present
> in any archive suites.
>
> Epochs are not included in the names of the files that compose source
> packages, or in the filenames of binary packages, so reusing a version
> number, even if the epoch differs, results in identically named files
> with different contents.  This can cause various problems.
>
> If you find yourself wanting to reuse the part of a version number
> after the epoch, you can just bump the Debian revision, which doesn't
> need to start at 1 or be consecutive.

I dropped the thing about tags as the solution of bumping the Debian
revision is simpler so it keeps Policy's suggested solution easier to
read.  Admittedly doesn't help with native packages but those can just
have their patch level bumped.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#881431: proposed wording

[Adam Borowski]

On Thu, Mar 29, 2018 at 08:02:48AM -0300, David Bremner wrote:
> Adam Borowski  writes:
> >
> > Sounds better than mine.  I'd re-add "once that package has been accepted
> > into the archive", to make it obvious that resubmissions to NEW and/or
> > mentors are expected to reuse version numbers of what they amend.
> 
> Personally, I usually increase version numbers in those situations. It's
> not like we're going to run out of version numbers...

Yeah, that's why my edit doesn't mandate either option.  It just would be
wrong to suddenly forbid the one that seems to be far more prevalent
currently -- at least without a discussion.

The policy should be clear wrt what's forbidden vs what's allowed,
merely recommending one particular way belongs to the devref.


Meow!
-- 
⢀⣴⠾⠻⢶⣦⠀ When I visited the US a couple decades ago, Hillary molested and
⣾⠁⢰⠒⠀⣿⡁ groped me.  You don't believe?  Well, the burden of proof is on you!
⢿⡄⠘⠷⠚⠋⠀ Flooding a douche with obviously false accusations makes your other
⠈⠳⣄ words dubious even when they happen to be true.

Bug#881431: proposed wording

[David Bremner]

Adam Borowski  writes:

>
> Sounds better than mine.  I'd re-add "once that package has been accepted
> into the archive", to make it obvious that resubmissions to NEW and/or
> mentors are expected to reuse version numbers of what they amend.

Personally, I usually increase version numbers in those situations. It's
not like we're going to run out of version numbers...

d

Bug#881431: proposed wording

[Adam Borowski]

On Wed, Mar 28, 2018 at 03:32:02PM -0700, Sean Whitton wrote:
> Suggested replacement:
> 
> The part of the version number after the epoch must not be reused for a
> version of the package with different contents, even if the version
> of the package previously using that part of the version number is
> no longer present in any archive suites.
> 
> Epochs are not included in the names of the files that compose
> source packages, or in the filenames of binary packages, so reusing
> a version number, even if the epoch differs, results in identically
> named files with different contents.  This causes various problems.

Sounds better than mine.  I'd re-add "once that package has been accepted
into the archive", to make it obvious that resubmissions to NEW and/or
mentors are expected to reuse version numbers of what they amend.


Meow!
-- 
⢀⣴⠾⠻⢶⣦⠀ When I visited the US a couple decades ago, Hillary molested and
⣾⠁⢰⠒⠀⣿⡁ groped me.  You don't believe?  Well, the burden of proof is on you!
⢿⡄⠘⠷⠚⠋⠀ Flooding a douche with obviously false accusations makes your other
⠈⠳⣄ words dubious even when they happen to be true.

Bug#881431: proposed wording

[Sean Whitton]

Hello Adam,

On Wed, Mar 28 2018, Adam Borowski wrote:

> Here's my proposed wording:

Thank you for working on this.

> .
> §3.2.2. Versions must be unique

"Uniqueness of version numbers" would be more fitting with Policy's
tone.

And versions are unique by definition :)  It's version numbers that are
the problem here.

> Because of a quirk of file naming, version numbers that are identical
> save for epoch cause problems, and thus must not be used.

This sentence is quite confusing.  It seems to suggest that the whole
reason version numbers should not be reused is because of a quirk in
file naming, which is false.

Further, if we're going to mention the quirk in file naming, we should
say what that quirk is, or people reading won't understand what's going
on.

Finally, you haven't given a sense to the verb phrase "use version
numbers that are identical" -- use them for what?

Suggested replacement:

The part of the version number after the epoch must not be reused for a
version of the package with different contents, even if the version
of the package previously using that part of the version number is
no longer present in any archive suites.

Epochs are not included in the names of the files that compose
source packages, or in the filenames of binary packages, so reusing
a version number, even if the epoch differs, results in identically
named files with different contents.  This causes various problems.

> In such case

I think we should say what the case is.

> you may bump the Debian revision (it doesn't need to
> start at 1 or be consecutive) or append a tag.

Policy doesn't define "tags" in version numbers so might be good to give
an example (possibly using the +really convention?).

> In these three namespaces: source, upstream (.orig), and binary, a
> combination of package name:version-without-epoch must never be reused
> once a package has been accepted into the archive, even after a
> release the package belonged to has been obsoleted.

I think the quoted sentence is obsoleted by what I wrote above, so can
be deleted.  But let me know what you think.

> WRT doing policy first before DAK/etc implementation: a maintainer in
> #887740 refused to make a version before such a requirement has been agreed
> upon -- thus, it'd be good to provide guidelines even before they're
> enforced with code.

Just to note that since Policy is about the contents of source and
binary packages, not about the behaviour of dak, this is a case where
our convention of changing the archive before changing Policy does not
apply, and so existing convention does not determine which should happen
first.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#881431: proposed wording

[Adam Borowski]

Control: tags -1 +patch


Here's my proposed wording:

.
§3.2.2. Versions must be unique

Because of a quirk of file naming, version numbers that are identical save
for epoch cause problems, and thus must not be used.  In such case you may
bump the Debian revision (it doesn't need to start at 1 or be consecutive)
or append a tag.  In these three namespaces: source, upstream (.orig), and
binary, a combination of package name:version-without-epoch must never be
reused once a package has been accepted into the archive, even after a
release the package belonged to has been obsoleted.
`

This should address all issues mentioned in this bug, plus a not entirely
obvious case of a new source package producing a binary with a name that
used to belong to another package.

It also forbids the secret tech of uploading 1.2.3.orig.tar.gz then
1.2.3.orig.tar.xz; this is sometimes useful but the confusion is not
worth it compared to adding a tag.

WRT doing policy first before DAK/etc implementation: a maintainer in
#887740 refused to make a version before such a requirement has been agreed
upon -- thus, it'd be good to provide guidelines even before they're
enforced with code.


Meow!
-- 
⢀⣴⠾⠻⢶⣦⠀ 
⣾⠁⢠⠒⠀⣿⡁ A dumb species has no way to open a tuna can.
⢿⡄⠘⠷⠚⠋⠀ A smart species invents a can opener.
⠈⠳⣄ A master species delegates.