Bug#891216: Requre d-devel consultation for epoch bump [and 2 more messages]

[Sean Whitton]

Hello,

On Fri, May 25 2018, Ian Jackson wrote:

> Sean Whitton writes ("Re: Bug#891216: Requre d-devel consultation for
>epoch bump [and 2 more messages]"):
>> On Fri, May 25 2018, Ian Jackson wrote:
>> > When we get to tidying this up, the epoch-ignoring new file name
>> > uniqueness section could probably do with a cross-reference.
>>
>> Do you mean 3.2.2?
>
> I think I do.  "Uniqueness of version numbers".

ISTM that your new section should refer to 3.2.2, because the
requirements of 3.2.2 are one reason to avoid epochs.  In the other
direction, however, I can't see right now what sort of cross reference
you are thinking should be inserted in 3.2.2.  A patch would be welcome.

This is all informative, so it doesn't needed to be seconded, so let's
not modify the patch to be seconded but instead make further commits --
my bug891216-spwhitton branch in the Policy repo has your patch applied.

>> I'm mildly distressed that we have two patches that I am hoping to
>> get into the next release of Policy that add subsubsubsections
>> (i.e. the section number contains three periods) but I think it's the
>> right thing to do in both cases.
>
> I did various git-grep to find out what rst syntax I should use for my
> subsubsection and discovered that there were quite a few already, all
> using ^.
>
> I don't think there is anything wrong with subsubsections.  They ease
> all of reading, navigation, cross-referencing, and referencing from
> elsewhere.

I assume you mean 'subsubsubsection(s)' throughout.

I was being misled by the fact that subsubsubsections are elided from
the table of contents generated by Sphinx into thinking that both the
patches introduced a subsubsubsection for the first time.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#891216: Requre d-devel consultation for epoch bump [and 2 more messages]

[Ian Jackson]

Sean Whitton writes ("Re: Bug#891216: Requre d-devel consultation for epoch 
bump [and 2 more messages]"):
> On Fri, May 25 2018, Ian Jackson wrote:
> > When we get to tidying this up, the epoch-ignoring new file name
> > uniqueness section could probably do with a cross-reference.
> 
> Do you mean 3.2.2?

I think I do.  "Uniqueness of version numbers".

> I'm mildly distressed that we have two patches that I am hoping to get
> into the next release of Policy that add subsubsubsections (i.e. the
> section number contains three periods) but I think it's the right thing
> to do in both cases.

I did various git-grep to find out what rst syntax I should use for my
subsubsection and discovered that there were quite a few already, all
using ^.

I don't think there is anything wrong with subsubsections.  They ease
all of reading, navigation, cross-referencing, and referencing from
elsewhere.

Regards,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#891216: Requre d-devel consultation for epoch bump [and 2 more messages]

[Sean Whitton]

Hello,

On Fri, May 25 2018, Ian Jackson wrote:

> When we get to tidying this up, the epoch-ignoring new file name
> uniqueness section could probably do with a cross-reference.

Do you mean 3.2.2?

> I did decide to make the text discouraging epochs a subsection.

This is good.  I'm also glad you included the point that epochs could
still be used for recovering from very serious mistakes.

On Fri, May 25 2018, Ian Jackson wrote:

> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 0771346..166cdd8 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -552,9 +552,10 @@ The three components here are:
>  omitted, in which case zero is assumed. If it is omitted then the
>  ``upstream_version`` may not contain any colons.
>
> -It is provided to allow mistakes in the version numbers of older
> -versions of a package, and also a package's previous version
> -numbering schemes, to be left behind.
> +Epochs can help when the upstream version numbering scheme
> +changes, but they must be used with care.  You should not change
> +the epoch, even in experimental, without getting consensus on
> +debian-devel first.
>
>  ``upstream_version``
>  This is the main part of the version number. It is usually the
> @@ -622,9 +623,23 @@ These two steps (comparing and removing initial 
> non-digit strings and
>  initial digit strings) are repeated until a difference is found or both
>  strings are exhausted.
>
> -Note that the purpose of epochs is to allow us to leave behind mistakes
> -in version numbering, and to cope with situations where the version
> -numbering scheme changes. It is *not* intended to cope with version
> +Epochs should be used sparingly
> +^^^
> +
> +Note that the purpose of epochs is to cope with situations where the
> +upstream version numbering scheme changes and to allow us to leave
> +behind serious mistakes.
> +If you think that increasing the epoch is the right solution,
> +you should consult debian-devel and get consensus before doing so
> +(even in experimental).
> +
> +Epochs should not be used when a package needs to be rolled back.
> +In that case, use the ``+really`` convention: for example, if you
> +uploaded ``2.3-3`` and now you need to go backwards to upstream 2.2,
> +call your reverting upload something like ``2.3+really2.2-1``.
> +Eventually, when we upload upstream 2.4, the +really part can go away.
> +
> +Epochs are also not intended to cope with version
>  numbers containing strings of letters which the package management
>  system cannot interpret (such as ``ALPHA`` or ``pre-``), or with silly
>  orderings.  [#]_

Seconded -- thank you for a nice patch.

I'm mildly distressed that we have two patches that I am hoping to get
into the next release of Policy that add subsubsubsections (i.e. the
section number contains three periods) but I think it's the right thing
to do in both cases.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#891216: Requre d-devel consultation for epoch bump [and 2 more messages]

[Ian Jackson]

Ian Jackson writes ("Re: Bug#891216: Requre d-devel consultation for epoch bump 
[and 2 more messages]"):
> Control: tags -1 + patch
> 
> Thanks for the feedback.  Please find attached a diff against current
> master.

The attachment seems to have got lost.  Sorry, here it is.

Ian.

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 0771346..166cdd8 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -552,9 +552,10 @@ The three components here are:
 omitted, in which case zero is assumed. If it is omitted then the
 ``upstream_version`` may not contain any colons.
 
-It is provided to allow mistakes in the version numbers of older
-versions of a package, and also a package's previous version
-numbering schemes, to be left behind.
+Epochs can help when the upstream version numbering scheme
+changes, but they must be used with care.  You should not change
+the epoch, even in experimental, without getting consensus on
+debian-devel first.
 
 ``upstream_version``
 This is the main part of the version number. It is usually the
@@ -622,9 +623,23 @@ These two steps (comparing and removing initial non-digit 
strings and
 initial digit strings) are repeated until a difference is found or both
 strings are exhausted.
 
-Note that the purpose of epochs is to allow us to leave behind mistakes
-in version numbering, and to cope with situations where the version
-numbering scheme changes. It is *not* intended to cope with version
+Epochs should be used sparingly
+^^^
+
+Note that the purpose of epochs is to cope with situations where the
+upstream version numbering scheme changes and to allow us to leave
+behind serious mistakes.
+If you think that increasing the epoch is the right solution,
+you should consult debian-devel and get consensus before doing so
+(even in experimental).
+
+Epochs should not be used when a package needs to be rolled back.
+In that case, use the ``+really`` convention: for example, if you
+uploaded ``2.3-3`` and now you need to go backwards to upstream 2.2,
+call your reverting upload something like ``2.3+really2.2-1``.
+Eventually, when we upload upstream 2.4, the +really part can go away.
+
+Epochs are also not intended to cope with version
 numbers containing strings of letters which the package management
 system cannot interpret (such as ``ALPHA`` or ``pre-``), or with silly
 orderings.  [#]_

Bug#891216: Requre d-devel consultation for epoch bump [and 2 more messages]

[Ian Jackson]

Control: tags -1 + patch

Thanks for the feedback.  Please find attached a diff against current
master.

Mattia Rizzolo writes ("Bug#891216: Requre d-devel consultation for epoch 
bump"):
> On Fri, Feb 23, 2018 at 01:26:01PM +, Ian Jackson wrote:
> >   + Epochs should not usually be used when
> >   + a package needs to be rolled back (use the +really convention)
> >   + or to
> 
> This needs to be reworded.  "the +really convention" is probably not
> really policy material (feels more like devref's) and therfore probably
> not mentioned here.

I agree with Sean on this.  So, instead, I have documented what I
think the +really convention consists of.

If this turns out to be controversial then IMO we should drop the
definition and leave a reference to an undefined term, since it is
better to encourage use of that convention, even if ill-defined, than
to let the reader use an epoch unaware that it's a bad idea.

Sean Whitton writes ("Bug#891216: Requre d-devel consultation for epoch bump"):
> On Mon, Feb 26 2018, Mattia Rizzolo wrote:
> > And with this the mention of d-devel happened twice in your patch.
> 
> This is Ian responding to the fact that epochs are discussed in two
> places.
> 
> I would rather fix that in a separate bug.

I have not dealt with this in my attached patch.  When we get to
tidying this up, the epoch-ignoring new file name uniqueness section
could probably do with a cross-reference.

I did decide to make the text discouraging epochs a subsection.

Sean Whitton writes ("Bug#891216: Requre d-devel consultation for epoch bump"):
> So I think we should have:
> 
> You should not change the epoch for a package before this has been
> discussed on the debian-devel mailing list and a consensus about
> doing that has been reached.
> 
> This is consistent with wording elsewhere in Policy.

I've adopted your wording, thanks.

> >   + If you think that increasing the epoch is the right situation,
> >   + please consult debian-devel before doing so
> >   + (even in experimental).
> 
> For consistency, s/please/you should/.

Updated this wording too.  I think you will like it better.

Thanks,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#891216: Requre d-devel consultation for epoch bump

[Sean Whitton]

Hello,

On Mon, Feb 26 2018, Mattia Rizzolo wrote:

> This needs to be reworded.  "the +really convention" is probably not
> really policy material (feels more like devref's) and therfore probably
> not mentioned here.

I disagree.  Policy often describes conventions; in particular,
conventions that exist in response to things that are forbidden or
required by Policy.

Moreover, we want someone reading about epochs to be hinted towards the
+really convention, without hoping that they just happen to head over to
devref right after.

> And with this the mention of d-devel happened twice in your patch.

This is Ian responding to the fact that epochs are discussed in two
places.

I would rather fix that in a separate bug.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#891216: Requre d-devel consultation for epoch bump

[Sean Whitton]

Hello Ian,

On Fri, Feb 23 2018, Ian Jackson wrote:

> We had another thread on debian-devel recently, in which it once again
> became evident that epochs are misunderstood.  Epoch bumps should be
> rare and there are often better solutions.  I suggest that we should
> ask people to consult debian-devel.

I agree.

> Also we should encourage the +really convention rather than epoch
> bumps.

I agree.

>   + Epochs can help when the upstream version numbering scheme
>   + changes, but they must be used with care.  In Debian, please
>   + consult debian-devel when changing the epoch.

This doesn't use one of the usual Policy terms "must", "should" or
"recommended", yet it's an imperative, so I find it ambiguous whether
this is a requirement of Policy or a suggested best practice.

So I think we should have:

You should not change the epoch for a package before this has been
discussed on the debian-devel mailing list and a consensus about
doing that has been reached.

This is consistent with wording elsewhere in Policy.

I also prefer to drop the "In Debian" because Policy does not usually
qualify Debian-specific practices, and if we are going to start doing
that, we should have a separate discussion and not let it hold up this
bug.

>   ...
>
> Note that the purpose of epochs is
>   - to allow us to leave behind mistakes in version numbering, and
> to cope with situations where the
>   + upstream
> version numbering scheme changes
>   + and to allow us to leave behind serious mistakes
> .
>   +
>   + Epochs should not usually be used when
>   + a package needs to be rolled back (use the +really convention)

I would prefer to see an explanation of the +really convention if you'd
care to write one, but that's informative so can be added later.

>   + or to
> cope with
>   - It is not intended to
> version numbers containing strings of letters which the package
> management system cannot interpret (such as ALPHA or pre-), or with
> silly orderings.
>   +
>   + If you think that increasing the epoch is the right situation,
>   + please consult debian-devel before doing so
>   + (even in experimental).

For consistency, s/please/you should/.

Seconds?

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#891216: Requre d-devel consultation for epoch bump

[Mattia Rizzolo]

On Fri, Feb 23, 2018 at 01:26:01PM +, Ian Jackson wrote:
> Concretely,
> 
> epoch
> 
>   This is a single (generally small) unsigned integer. It may be
>   omitted, in which case zero is assumed. If it is omitted then the
>   upstream_version may not contain any colons.
>   -
>   - It is provided to allow mistakes in the version numbers of older
>   - versions of a package, and also a s previous version numbering
>   - schemes, to be left behind.
>   - package
>   +
>   + Epochs can help when the upstream version numbering scheme
>   + changes, but they must be used with care.  In Debian, please
>   + consult debian-devel when changing the epoch.
> 
>   ...
> 
> Note that the purpose of epochs is
>   - to allow us to leave behind mistakes in version numbering, and
> to cope with situations where the
>   + upstream
> version numbering scheme changes
>   + and to allow us to leave behind serious mistakes
> .
>   +
>   + Epochs should not usually be used when
>   + a package needs to be rolled back (use the +really convention)
>   + or to

This needs to be reworded.  "the +really convention" is probably not
really policy material (feels more like devref's) and therfore probably
not mentioned here.

> cope with
>   - It is not intended to
> version numbers containing strings of letters which the package
> management system cannot interpret (such as ALPHA or pre-), or with
> silly orderings.
>   +
>   + If you think that increasing the epoch is the right situation,
>   + please consult debian-devel before doing so
>   + (even in experimental).

And with this the mention of d-devel happened twice in your patch.



I'm very happy to second this idea, but I believe the actual text needs
to be improved.  I'll leave that to policy editors though, as it's
really not my field of competence :)
BTW, I believe that when you propose a patch like this, pretty much
everybody would like to see the filename and the hook delimiters (i.e.
everything git diff gives you).

-- 
regards,
Mattia Rizzolo

GPG Key: 66AE 2B4A FCCF 3F52 DA18  4D18 4B04 3FCD B944 4540  .''`.
more about me:  https://mapreri.org : :'  :
Launchpad user: https://launchpad.net/~mapreri  `. `'`
Debian QA page: https://qa.debian.org/developer.php?login=mattia  `-


signature.asc
Description: PGP signature

Bug#891216: Requre d-devel consultation for epoch bump

[Ian Jackson]

Guillem Jover writes ("Re: Bug#891216: Requre d-devel consultation for epoch 
bump"):
> I also ended up writing a new dpkg FAQ entry, given that thread:
> 
>   
> <https://wiki.debian.org/Teams/Dpkg/FAQ#Q:_What_are_version_epochs_and_why_and_when_are_they_needed.3F>

Thanks.

Would you care to second my policy amendment ?

Ian.

Bug#891216: Requre d-devel consultation for epoch bump

[Guillem Jover]

Hi!

On Fri, 2018-02-23 at 13:26:01 +, Ian Jackson wrote:
> Package: debian-policy
> Version: 4.1.3.0

> We had another thread on debian-devel recently, in which it once again
> became evident that epochs are misunderstood.  Epoch bumps should be
> rare and there are often better solutions.  I suggest that we should
> ask people to consult debian-devel.
> 
> Also we should encourage the +really convention rather than epoch
> bumps.

I also ended up writing a new dpkg FAQ entry, given that thread:

  


Thanks,
Guillem

Bug#891216: Requre d-devel consultation for epoch bump

[Ian Jackson]

David Bremner writes ("Bug#891216: Requre d-devel consultation for epoch bump"):
> I find the existing use of the debian-devel list in policy strange, and
> am unenthusiastic about expanding it.  It's not a "must-read" list for
> debian contributors, and it is (or was, last time I subscribed) an
> extremely noisy forum.  I concede that your proposed use of the list is
> consistent with existing ones.

The point of gettting review from d-devel is not to notify everyone
who might be interested.  It is to get some peer review from the
cross-section of people who _do_ read that list.

There is a lot of expertise there and escalating difficult things
there is very effective.  (It's less good for things which are
politically contentious, but as a project we are very poor at those
and d-devel is often the least bad option.  Anyway, that's not
relevant here.)

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#891216: Requre d-devel consultation for epoch bump

[David Bremner]

Ian Jackson  writes:

> Package: debian-policy
> Version: 4.1.3.0
>
> We had another thread on debian-devel recently, in which it once again
> became evident that epochs are misunderstood.  Epoch bumps should be
> rare and there are often better solutions.  I suggest that we should
> ask people to consult debian-devel.
>
> Also we should encourage the +really convention rather than epoch
> bumps.

Without taking a position on epochs...

I find the existing use of the debian-devel list in policy strange, and
am unenthusiastic about expanding it.  It's not a "must-read" list for
debian contributors, and it is (or was, last time I subscribed) an
extremely noisy forum.  I concede that your proposed use of the list is
consistent with existing ones.

d

Bug#891216: Requre d-devel consultation for epoch bump

[Ian Jackson]

Package: debian-policy
Version: 4.1.3.0

We had another thread on debian-devel recently, in which it once again
became evident that epochs are misunderstood.  Epoch bumps should be
rare and there are often better solutions.  I suggest that we should
ask people to consult debian-devel.

Also we should encourage the +really convention rather than epoch
bumps.

Concretely,

epoch

This is a single (generally small) unsigned integer. It may be
omitted, in which case zero is assumed. If it is omitted then the
upstream_version may not contain any colons.
  -
  - It is provided to allow mistakes in the version numbers of older
  - versions of a package, and also a s previous version numbering
  - schemes, to be left behind.
  - package
  +
  + Epochs can help when the upstream version numbering scheme
  + changes, but they must be used with care.  In Debian, please
  + consult debian-devel when changing the epoch.

  ...

Note that the purpose of epochs is
  - to allow us to leave behind mistakes in version numbering, and
to cope with situations where the
  + upstream
version numbering scheme changes
  + and to allow us to leave behind serious mistakes
.
  +
  + Epochs should not usually be used when
  + a package needs to be rolled back (use the +really convention)
  + or to
cope with
  - It is not intended to
version numbers containing strings of letters which the package
management system cannot interpret (such as ALPHA or pre-), or with
silly orderings.
  +
  + If you think that increasing the epoch is the right situation,
  + please consult debian-devel before doing so
  + (even in experimental).

Ian.