clarification of REVISION and EPOCH documentation.

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

clarification of REVISION and EPOCH documentation.

Paco Esteban-2
Hi ports@,

Find attached 3 diffs for bsd.ports.mk(5), packages-specs(7) and
www/faq/ports/guide.html

This comes from a question I asked yesterday about REVISION and EPOCH
which naddy@ tried to explain to me.

I think this explanation was really clear and simple and I have been
encouraged to add it to the related documentation.

I basically repeated/adapted some bits and pieces between the 3 sources
and added naddy's "graphical" explanation.

I'm aware this changes are pretty rough, but I send them hoping to get
comments and discussion.

Cheers,

--
Paco Esteban.
0x5818130B8A6DBC03

bsd.port.mk.diff (677 bytes) Download Attachment
packages-specs.diff (1K) Download Attachment
ports-guide.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Stuart Henderson
On 2020/03/14 17:09, Paco Esteban wrote:

> Hi ports@,
>
> Find attached 3 diffs for bsd.ports.mk(5), packages-specs(7) and
> www/faq/ports/guide.html
>
> This comes from a question I asked yesterday about REVISION and EPOCH
> which naddy@ tried to explain to me.
>
> I think this explanation was really clear and simple and I have been
> encouraged to add it to the related documentation.
>
> I basically repeated/adapted some bits and pieces between the 3 sources
> and added naddy's "graphical" explanation.
>
> I'm aware this changes are pretty rough, but I send them hoping to get
> comments and discussion.
>
> Cheers,
>
> --
> Paco Esteban.
> 0x5818130B8A6DBC03

> Index: bsd.port.mk.5
> ===================================================================
> RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> retrieving revision 1.527
> diff -u -p -r1.527 bsd.port.mk.5
> --- bsd.port.mk.5 6 Mar 2020 15:22:44 -0000 1.527
> +++ bsd.port.mk.5 14 Mar 2020 14:46:18 -0000
> @@ -1632,6 +1632,9 @@ If set to
>  will not open changed files in an editor.
>  .It Ev EPOCH
>  Epoch number of the current package.
> +Used when version numbering changes completely upstream or an update has to be
> +reverted.
> +It always goes forward.

maybe this?

...
Used when the port version number is changed but the new version
is not regarded by
.Xr packages-specs 5
as being newer.
...

Once added, it cannot be removed or go backwards.

>  Defaults to empty (no need for numbering changes), then
>  numbering starts at 0.
>  Gets automatically incorporated into

Perhaps we should also mention that if a port depends on another port
using a version spec ("foo->=1.1" or similar), the version spec in the
dependent port must be changed too... Not sure how to word it though.

> Index: packages-specs.7
> ===================================================================
> RCS file: /home/cvs/src/share/man/man7/packages-specs.7,v
> retrieving revision 1.25
> diff -u -p -r1.25 packages-specs.7
> --- packages-specs.7 27 Oct 2014 22:45:30 -0000 1.25
> +++ packages-specs.7 14 Mar 2020 15:00:42 -0000
> @@ -144,12 +144,39 @@ then normal version, and finally
>  .El
>  .El
>  .Pp
> -In some rare cases, version numbering changes completely upstream.
> +In some rare cases, version numbering changes completely upstream, or something
> +unexpected happens and an update has to be reverted.

In some rare cases, a change to a port would cause the version number
to compare as older than the previous version.
This happens if an update is reverted, if upstream's numbering scheme
changes completely, or if their usual scheme does not align with
the one used by
.Ox .

>  A version style marker, of the form
>  .Sq v0 ,
>  .Sq v1 ...
>  can be appended to the version number (after the patch level)
>  to denote the new numbering scheme.

This is added by setting
???some markup??? EPOCH
in the port Makefile.

> +Combined with
> +.Ev REVISION ,
> +this leaves the version ordering as follows:

Maybe I missed something in what's meant, but the following examples
are all exactly the wrong way round.. 0.1p0 is newer than 0.1,
0.2 is newer than 0.1p0, etc.

> +.Bl -dash
> +.It
> +"0.1p0" is older than "0.1"
> +.It
> +"0.2" is older than "0.1p0" (or
> +.Sq p1 ,
> +.Sq p2 ... )
> +.It
> +"0.1v0" is older than "0.2" (or any other version number without
> +.Sq v )
> +.It
> +"0.1p0v0" is older than "0.1v0".
> +Just as showed in the first point.
> +.It
> +"0.2v0" is older than "0.1p0v0".
> +The same as the second point.
> +.It
> +"0.1v1" is older than "0.2v0" (or any other version with a lower
> +.Sq v
> +value)
> +.El
> +.El
> +.Pp
>  See
>  .Ev EPOCH
>  in

> Index: faq/ports/guide.html
> ===================================================================
> RCS file: /home/cvs/www/faq/ports/guide.html,v
> retrieving revision 1.89
> diff -u -p -r1.89 guide.html
> --- faq/ports/guide.html 28 Sep 2019 21:35:05 -0000 1.89
> +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -0000
> @@ -1131,6 +1131,8 @@ changes to patches or build flags.
>  If the upstream version has not changed, the package name bump is done
>  by incrementing <code>REVISION</code> if already present, otherwise adding
>  <code>REVISION = 0</code> towards the top of the Makefile.
> +This will add <code>p${REVISION}</code> to <code>FULLPKGNAME</code> to form a full
> +package-name conforming to packages-specs(7).
>  
>  <li>
>  Version numbers always go forward.
> @@ -1138,6 +1140,8 @@ If something unexpected happens and you
>  upstream numbering changes completely so that the version number appears
>  to go backwards, you must use <code>EPOCH</code> to make sure pkg_add(1) sees
>  the package as a newer package.
> +This will add <code>v${EPOCH}</code> to <code>FULLPKGNAME</code> to form a full
> +package-name conforming to packages-specs(7).
>  
>  <li>
>  If the package does not build, no bump is needed: changes to restore a port
> @@ -1153,6 +1157,11 @@ The package system uses a signature mech
>  is fully identified by its package names, plus the dependencies against
>  which it was built, plus the version numbers of all shared libraries it
>  contains.
> +
> +<li>
> +The version comparison ordering can be summarized as:
> +<code>0.1 &lt; 0.1p0 &lt; 0.2 &lt; 0.1v0 &lt; 0.1p0v0 &lt; 0.2v0 &lt; 0.1v1</code>.
> +Check packages-specs(7) for more detailed information.
>  </ul>
>  
>  Part of the work will happen before the update itself.

Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Paco Esteban-2
On Sat, 14 Mar 2020, Stuart Henderson wrote:

> > Index: bsd.port.mk.5
> > ===================================================================
> > RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> > retrieving revision 1.527
> > diff -u -p -r1.527 bsd.port.mk.5
> > --- bsd.port.mk.5 6 Mar 2020 15:22:44 -0000 1.527
> > +++ bsd.port.mk.5 14 Mar 2020 14:46:18 -0000
> > @@ -1632,6 +1632,9 @@ If set to
> >  will not open changed files in an editor.
> >  .It Ev EPOCH
> >  Epoch number of the current package.
> > +Used when version numbering changes completely upstream or an update has to be
> > +reverted.
> > +It always goes forward.
>
> maybe this?
>
> ...
> Used when the port version number is changed but the new version
> is not regarded by
> .Xr packages-specs 5
> as being newer.
> ...
>
> Once added, it cannot be removed or go backwards.
I like your wording better.  Is more generic, and less repetitive as we
already talk about those 2 cases in other parts of the doc.
Not sure it "fits well" in the description, though.  This is how it
reads with your changes (I added them nonetheless):

EPOCH   Epoch number of the current package.  Used when the port version
        is changed but the new version is not regarded by
        packages-specs(5) as being newer.  Once added, it cannot be
        removed or go backwards.  Defaults to empty (no need for
        numbering changes), then numbering starts at 0.  Gets
        automatically incorporated into FULLPKGNAME as ‘v${EPOCH}’ to
        form a full package-name conforming to packages-specs(7).

> >  Defaults to empty (no need for numbering changes), then
> >  numbering starts at 0.
> >  Gets automatically incorporated into
>
> Perhaps we should also mention that if a port depends on another port
> using a version spec ("foo->=1.1" or similar), the version spec in the
> dependent port must be changed too... Not sure how to word it though.

oh, that did not occur to me ...  You mean that if port foo/bar gets
EPOCH = 0, then all dependent ports should change it's dependencies
declarations from foo/bar>=1.1 to foo/bar>=1.1v0 ??

> > Index: packages-specs.7
> > ===================================================================
> > RCS file: /home/cvs/src/share/man/man7/packages-specs.7,v
> > retrieving revision 1.25
> > diff -u -p -r1.25 packages-specs.7
> > --- packages-specs.7 27 Oct 2014 22:45:30 -0000 1.25
> > +++ packages-specs.7 14 Mar 2020 15:00:42 -0000
> > @@ -144,12 +144,39 @@ then normal version, and finally
> >  .El
> >  .El
> >  .Pp
> > -In some rare cases, version numbering changes completely upstream.
> > +In some rare cases, version numbering changes completely upstream, or something
> > +unexpected happens and an update has to be reverted.
>
> In some rare cases, a change to a port would cause the version number
> to compare as older than the previous version.
> This happens if an update is reverted, if upstream's numbering scheme
> changes completely, or if their usual scheme does not align with
> the one used by
> .Ox .
This reads definitely better.  Adding it.

> >  A version style marker, of the form
> >  .Sq v0 ,
> >  .Sq v1 ...
> >  can be appended to the version number (after the patch level)
> >  to denote the new numbering scheme.
>
> This is added by setting
> ???some markup??? EPOCH
> in the port Makefile.

Added too.
I used `.Ev` here.  Not sure is the correct macro, but as this is close
to an environment variable I think is ok ...

> Maybe I missed something in what's meant, but the following examples
> are all exactly the wrong way round.. 0.1p0 is newer than 0.1,
> 0.2 is newer than 0.1p0, etc.

You're totally right ...  I did it backwards.  I was trying to maintain
the wording coherent with the previous list (use older instead of newer)
and don't know what happened in my head.  Fixed it.

All 3 diffs attached again for convenience.

--
Paco Esteban.
0x5818130B8A6DBC03

bsd.port.mk.diff (731 bytes) Download Attachment
packages-specs.diff (1K) Download Attachment
ports-guide.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Marc Espie-2
On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
> oh, that did not occur to me ...  You mean that if port foo/bar gets
> EPOCH = 0, then all dependent ports should change it's dependencies
> declarations from foo/bar>=1.1 to foo/bar>=1.1v0 ??

Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
and tweaking _print-metadata, so we didn't hav to change every
dependent port.

You still need to bump REVISION in dependent port when you change PKGSPEC
though.

Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Paco Esteban-2
On Sun, 15 Mar 2020, Marc Espie wrote:

> On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
> > oh, that did not occur to me ...  You mean that if port foo/bar gets
> > EPOCH = 0, then all dependent ports should change it's dependencies
> > declarations from foo/bar>=1.1 to foo/bar>=1.1v0 ??
>
> Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
> and tweaking _print-metadata, so we didn't hav to change every
> dependent port.
>
> You still need to bump REVISION in dependent port when you change PKGSPEC
> though.
Thanks Marc, I tried to include that too.
All patches updated and attached again.

Cheers,

--
Paco Esteban.
0x5818130B8A6DBC03

bsd.port.mk.diff (1K) Download Attachment
packages-specs.diff (1K) Download Attachment
ports-guide.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Marc Espie-2
On Wed, Mar 25, 2020 at 09:11:14PM +0100, Paco Esteban wrote:

> On Sun, 15 Mar 2020, Marc Espie wrote:
>
> > On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
> > > oh, that did not occur to me ...  You mean that if port foo/bar gets
> > > EPOCH = 0, then all dependent ports should change it's dependencies
> > > declarations from foo/bar>=1.1 to foo/bar>=1.1v0 ??
> >
> > Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
> > and tweaking _print-metadata, so we didn't hav to change every
> > dependent port.
> >
> > You still need to bump REVISION in dependent port when you change PKGSPEC
> > though.
>
> Thanks Marc, I tried to include that too.
> All patches updated and attached again.

Oh sorry, I only intended to explain the history of things.

I think that PKGSPEC is too much detail in the documentation. It's
still supposed to be a reference manual, this does not belong in the man
page, possibly in the web page, but this will turn people away from
the manpage.

Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Jeremie Courreges-Anglas-2
In reply to this post by Paco Esteban-2
On Wed, Mar 25 2020, Paco Esteban <[hidden email]> wrote:

> On Sun, 15 Mar 2020, Marc Espie wrote:
>
>> On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
>> > oh, that did not occur to me ...  You mean that if port foo/bar gets
>> > EPOCH = 0, then all dependent ports should change it's dependencies
>> > declarations from foo/bar>=1.1 to foo/bar>=1.1v0 ??
>>
>> Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
>> and tweaking _print-metadata, so we didn't hav to change every
>> dependent port.
>>
>> You still need to bump REVISION in dependent port when you change PKGSPEC
>> though.
>
> Thanks Marc, I tried to include that too.
> All patches updated and attached again.
>
> Cheers,

Comments inline,

> Index: bsd.port.mk.5
> ===================================================================
> RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> retrieving revision 1.528
> diff -u -p -r1.528 bsd.port.mk.5
> --- bsd.port.mk.5 24 Mar 2020 14:59:52 -0000 1.528
> +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -0000
> @@ -1650,6 +1650,10 @@ If set to
>  will not open changed files in an editor.
>  .It Ev EPOCH
>  Epoch number of the current package.
> +Used when the port version is changed but the new version is not regarded by
> +.Xr packages-specs 5

5 -> 7

> +as being newer.
> +Once added, it cannot be removed or go backwards.

otherwise, ok jca@ for this hunk

>  Defaults to empty (no need for numbering changes), then
>  numbering starts at 0.
>  Gets automatically incorporated into
> @@ -1658,6 +1662,12 @@ as
>  .Sq v${EPOCH}
>  to form a full package-name conforming to
>  .Xr packages-specs 7 .
> +If there are dependent packages that use a version spec, this has to be
> +adjusted for each one or
> +.Ev PKGSPEC
> +changed on the affected package and
> +.Ev REVISION
> +bumped for all the dependencies.

Hmm, like Marc said this is not the place to mention PKGSPEC.

>  .It Ev ERRORS
>  List of errors found while parsing the port's Makefile.
>  Display the errors before making any target, and if any error starts with
>
> [3. text/plain; packages-specs.diff]
> Index: packages-specs.7
> ===================================================================
> RCS file: /home/cvs/src/share/man/man7/packages-specs.7,v
> retrieving revision 1.25
> diff -u -p -r1.25 packages-specs.7
> --- packages-specs.7 27 Oct 2014 22:45:30 -0000 1.25
> +++ packages-specs.7 15 Mar 2020 11:25:27 -0000
> @@ -144,12 +144,46 @@ then normal version, and finally
>  .El
>  .El
>  .Pp
> -In some rare cases, version numbering changes completely upstream.
> +In some rare cases, a change to a port would cause the version number to
> +compare as older than the previous version.
> +This happens if an update is reverted, if upstream's numbering scheme changes
> +completely, or if their usual scheme does not align with the one used by
> +.Ox .

ok jca@ for this hunk

>  A version style marker, of the form
>  .Sq v0 ,
>  .Sq v1 ...
>  can be appended to the version number (after the patch level)
>  to denote the new numbering scheme.
> +This is added by setting
> +.Ev EPOCH
> +in the port Makefile.
> +Combined with
> +.Ev REVISION ,
> +this leaves the version ordering as follows:
> +.Bl -dash
> +.It
> +"0.1" is older than "0.1p0"
> +.It
> +"0.1p0" (or
> +.Sq p1 ,
> +.Sq p2 ... )
> +is older than "0.2"
> +.It
> +"0.2" is older than "0.1v0" (or any other version number without
> +.Sq v )
> +.It
> +"0.1v0" is older than "0.1p0v0".
> +Just as showed in the first point.
> +.It
> +"0.1p0v0" is older than "0.2v0".
> +The same as the second point.
> +.It
> +"0.2v0" is older than "0.1v1" (or any other version with a lower
> +.Sq v
> +value)
> +.El
> +.El
> +.Pp

I find this a bit too chatty.  Can we find a single sentence that
explains what happens?

  ...
  A version style marker, of the form ‘v0’, ‘v1 ...’ can be appended to the
  version number (after the patch level) to denote the new numbering
  scheme.
 +This marker takes precedence over the regular package version.

Thoughts?

>  See
>  .Ev EPOCH
>  in
>
> [4. text/plain; ports-guide.diff]
> Index: faq/ports/guide.html
> ===================================================================
> RCS file: /home/cvs/www/faq/ports/guide.html,v
> retrieving revision 1.89
> diff -u -p -r1.89 guide.html
> --- faq/ports/guide.html 28 Sep 2019 21:35:05 -0000 1.89
> +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -0000
> @@ -1131,6 +1131,8 @@ changes to patches or build flags.
>  If the upstream version has not changed, the package name bump is done
>  by incrementing <code>REVISION</code> if already present, otherwise adding
>  <code>REVISION = 0</code> towards the top of the Makefile.
> +This will add <code>p${REVISION}</code> to <code>FULLPKGNAME</code> to form a full
> +package-name conforming to packages-specs(7).
>  
>  <li>
>  Version numbers always go forward.
> @@ -1138,6 +1140,8 @@ If something unexpected happens and you
>  upstream numbering changes completely so that the version number appears
>  to go backwards, you must use <code>EPOCH</code> to make sure pkg_add(1) sees
>  the package as a newer package.
> +This will add <code>v${EPOCH}</code> to <code>FULLPKGNAME</code> to form a full
> +package-name conforming to packages-specs(7).
>  
>  <li>
>  If the package does not build, no bump is needed: changes to restore a port
> @@ -1153,6 +1157,11 @@ The package system uses a signature mech
>  is fully identified by its package names, plus the dependencies against
>  which it was built, plus the version numbers of all shared libraries it
>  contains.

I'd be tempted to leave this as is, or only add something like what you
propose below.  I'm not objecting though.  :)

> +
> +<li>
> +The version comparison ordering can be summarized as:
> +<code>0.1 &lt; 0.1p0 &lt; 0.2 &lt; 0.1v0 &lt; 0.1p0v0 &lt; 0.2v0 &lt; 0.1v1</code>.
> +Check packages-specs(7) for more detailed information.
>  </ul>
>  
>  Part of the work will happen before the update itself.

--
jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF  DDCC 0DFA 74AE 1524 E7EE

Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Paco Esteban-2
Attached the 3 modified diffs again, and some comments inline.

On Thu, 26 Mar 2020, Jeremie Courreges-Anglas wrote:

> > Index: bsd.port.mk.5
> > ===================================================================
> > RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> > retrieving revision 1.528
> > diff -u -p -r1.528 bsd.port.mk.5
> > --- bsd.port.mk.5 24 Mar 2020 14:59:52 -0000 1.528
> > +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -0000
> > @@ -1650,6 +1650,10 @@ If set to
> >  will not open changed files in an editor.
> >  .It Ev EPOCH
> >  Epoch number of the current package.
> > +Used when the port version is changed but the new version is not regarded by
> > +.Xr packages-specs 5
>
> 5 -> 7
fixed.

> >  Defaults to empty (no need for numbering changes), then
> >  numbering starts at 0.
> >  Gets automatically incorporated into
> > @@ -1658,6 +1662,12 @@ as
> >  .Sq v${EPOCH}
> >  to form a full package-name conforming to
> >  .Xr packages-specs 7 .
> > +If there are dependent packages that use a version spec, this has to be
> > +adjusted for each one or
> > +.Ev PKGSPEC
> > +changed on the affected package and
> > +.Ev REVISION
> > +bumped for all the dependencies.
>
> Hmm, like Marc said this is not the place to mention PKGSPEC.
Yup, I misunderstood his message.  I've removed it.

> >  A version style marker, of the form
> >  .Sq v0 ,
> >  .Sq v1 ...
> >  can be appended to the version number (after the patch level)
> >  to denote the new numbering scheme.
> > +This is added by setting
> > +.Ev EPOCH
> > +in the port Makefile.
> > +Combined with
> > +.Ev REVISION ,
> > +this leaves the version ordering as follows:
> > +.Bl -dash
> > +.It
> > +"0.1" is older than "0.1p0"
> > +.It
> > +"0.1p0" (or
> > +.Sq p1 ,
> > +.Sq p2 ... )
> > +is older than "0.2"
> > +.It
> > +"0.2" is older than "0.1v0" (or any other version number without
> > +.Sq v )
> > +.It
> > +"0.1v0" is older than "0.1p0v0".
> > +Just as showed in the first point.
> > +.It
> > +"0.1p0v0" is older than "0.2v0".
> > +The same as the second point.
> > +.It
> > +"0.2v0" is older than "0.1v1" (or any other version with a lower
> > +.Sq v
> > +value)
> > +.El
> > +.El
> > +.Pp
>
> I find this a bit too chatty.  Can we find a single sentence that
> explains what happens?
>
>   ...
>   A version style marker, of the form ‘v0’, ‘v1 ...’ can be appended to the
>   version number (after the patch level) to denote the new numbering
>   scheme.
>  +This marker takes precedence over the regular package version.
>
> Thoughts?
Take a look at the new diff.  I removed the chatty list and merged your
sentence with the last part of mine.  I think is clear now.  It reads
like this:

  In some rare cases, a change to a port would cause the version number to
  compare as older than the previous version.  This happens if an update is
  reverted, if upstream's numbering scheme changes completely, or if their
  usual scheme does not align with the one used by OpenBSD.  A version
  style marker, of the form ‘v0’, ‘v1 ...’ can be appended to the version
  number (after the patch level) to denote the new numbering scheme.  This
  marker is added by setting EPOCH in the port Makefile and it takes
  precedence over the regular package version.  See bsd.port.mk(5).

> > Index: faq/ports/guide.html
> > ===================================================================
> > RCS file: /home/cvs/www/faq/ports/guide.html,v
> > retrieving revision 1.89
> > diff -u -p -r1.89 guide.html
> > --- faq/ports/guide.html 28 Sep 2019 21:35:05 -0000 1.89
> > +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -0000
> > @@ -1131,6 +1131,8 @@ changes to patches or build flags.
> >  If the upstream version has not changed, the package name bump is done
> >  by incrementing <code>REVISION</code> if already present, otherwise adding
> >  <code>REVISION = 0</code> towards the top of the Makefile.
> > +This will add <code>p${REVISION}</code> to <code>FULLPKGNAME</code> to form a full
> > +package-name conforming to packages-specs(7).
This is wrong, not sure how it get there.  I removed it.

> >  <li>
> >  Version numbers always go forward.
> > @@ -1138,6 +1140,8 @@ If something unexpected happens and you
> >  upstream numbering changes completely so that the version number appears
> >  to go backwards, you must use <code>EPOCH</code> to make sure pkg_add(1) sees
> >  the package as a newer package.
> > +This will add <code>v${EPOCH}</code> to <code>FULLPKGNAME</code> to form a full
> > +package-name conforming to packages-specs(7).
> >  
> >  <li>
> >  If the package does not build, no bump is needed: changes to restore a port
> > @@ -1153,6 +1157,11 @@ The package system uses a signature mech
> >  is fully identified by its package names, plus the dependencies against
> >  which it was built, plus the version numbers of all shared libraries it
> >  contains.
>
> I'd be tempted to leave this as is, or only add something like what you
> propose below.  I'm not objecting though.  :)
I've kept it for now, but not sure it adds much ...

>
> > +
> > +<li>
> > +The version comparison ordering can be summarized as:
> > +<code>0.1 &lt; 0.1p0 &lt; 0.2 &lt; 0.1v0 &lt; 0.1p0v0 &lt; 0.2v0 &lt; 0.1v1</code>.
> > +Check packages-specs(7) for more detailed information.
> >  </ul>

This is the sentence that triggered all this.  I kind of like how visual
it is, so I would keep it.

Cheers,

--
Paco Esteban.
0x5818130B8A6DBC03

bsd.port.mk.diff (732 bytes) Download Attachment
packages-specs.diff (1K) Download Attachment
ports-guide.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Marc Espie-2
On Thu, Mar 26, 2020 at 10:34:24AM +0100, Paco Esteban wrote:

> Attached the 3 modified diffs again, and some comments inline.
>
> On Thu, 26 Mar 2020, Jeremie Courreges-Anglas wrote:
>
> > > Index: bsd.port.mk.5
> > > ===================================================================
> > > RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> > > retrieving revision 1.528
> > > diff -u -p -r1.528 bsd.port.mk.5
> > > --- bsd.port.mk.5 24 Mar 2020 14:59:52 -0000 1.528
> > > +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -0000
> > > @@ -1650,6 +1650,10 @@ If set to
> > >  will not open changed files in an editor.
> > >  .It Ev EPOCH
> > >  Epoch number of the current package.
> > > +Used when the port version is changed but the new version is not regarded by
> > > +.Xr packages-specs 5
> >
> > 5 -> 7
>
> fixed.
>
> > >  Defaults to empty (no need for numbering changes), then
> > >  numbering starts at 0.
> > >  Gets automatically incorporated into
> > > @@ -1658,6 +1662,12 @@ as
> > >  .Sq v${EPOCH}
> > >  to form a full package-name conforming to
> > >  .Xr packages-specs 7 .
> > > +If there are dependent packages that use a version spec, this has to be
> > > +adjusted for each one or
> > > +.Ev PKGSPEC
> > > +changed on the affected package and
> > > +.Ev REVISION
> > > +bumped for all the dependencies.
> >
> > Hmm, like Marc said this is not the place to mention PKGSPEC.
>
> Yup, I misunderstood his message.  I've removed it.
>
> > >  A version style marker, of the form
> > >  .Sq v0 ,
> > >  .Sq v1 ...
> > >  can be appended to the version number (after the patch level)
> > >  to denote the new numbering scheme.
> > > +This is added by setting
> > > +.Ev EPOCH
> > > +in the port Makefile.
> > > +Combined with
> > > +.Ev REVISION ,
> > > +this leaves the version ordering as follows:
> > > +.Bl -dash
> > > +.It
> > > +"0.1" is older than "0.1p0"
> > > +.It
> > > +"0.1p0" (or
> > > +.Sq p1 ,
> > > +.Sq p2 ... )
> > > +is older than "0.2"
> > > +.It
> > > +"0.2" is older than "0.1v0" (or any other version number without
> > > +.Sq v )
> > > +.It
> > > +"0.1v0" is older than "0.1p0v0".
> > > +Just as showed in the first point.
> > > +.It
> > > +"0.1p0v0" is older than "0.2v0".
> > > +The same as the second point.
> > > +.It
> > > +"0.2v0" is older than "0.1v1" (or any other version with a lower
> > > +.Sq v
> > > +value)
> > > +.El
> > > +.El
> > > +.Pp
> >
> > I find this a bit too chatty.  Can we find a single sentence that
> > explains what happens?
> >
> >   ...
> >   A version style marker, of the form ‘v0’, ‘v1 ...’ can be appended to the
> >   version number (after the patch level) to denote the new numbering
> >   scheme.
> >  +This marker takes precedence over the regular package version.
> >
> > Thoughts?
>
> Take a look at the new diff.  I removed the chatty list and merged your
> sentence with the last part of mine.  I think is clear now.  It reads
> like this:
>
>   In some rare cases, a change to a port would cause the version number to
>   compare as older than the previous version.  This happens if an update is
>   reverted, if upstream's numbering scheme changes completely, or if their
>   usual scheme does not align with the one used by OpenBSD.  A version
>   style marker, of the form ‘v0’, ‘v1 ...’ can be appended to the version
>   number (after the patch level) to denote the new numbering scheme.  This
>   marker is added by setting EPOCH in the port Makefile and it takes
>   precedence over the regular package version.  See bsd.port.mk(5).
>
> > > Index: faq/ports/guide.html
> > > ===================================================================
> > > RCS file: /home/cvs/www/faq/ports/guide.html,v
> > > retrieving revision 1.89
> > > diff -u -p -r1.89 guide.html
> > > --- faq/ports/guide.html 28 Sep 2019 21:35:05 -0000 1.89
> > > +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -0000
> > > @@ -1131,6 +1131,8 @@ changes to patches or build flags.
> > >  If the upstream version has not changed, the package name bump is done
> > >  by incrementing <code>REVISION</code> if already present, otherwise adding
> > >  <code>REVISION = 0</code> towards the top of the Makefile.
> > > +This will add <code>p${REVISION}</code> to <code>FULLPKGNAME</code> to form a full
> > > +package-name conforming to packages-specs(7).
>
> This is wrong, not sure how it get there.  I removed it.
>
> > >  <li>
> > >  Version numbers always go forward.
> > > @@ -1138,6 +1140,8 @@ If something unexpected happens and you
> > >  upstream numbering changes completely so that the version number appears
> > >  to go backwards, you must use <code>EPOCH</code> to make sure pkg_add(1) sees
> > >  the package as a newer package.
> > > +This will add <code>v${EPOCH}</code> to <code>FULLPKGNAME</code> to form a full
> > > +package-name conforming to packages-specs(7).
> > >  
> > >  <li>
> > >  If the package does not build, no bump is needed: changes to restore a port
> > > @@ -1153,6 +1157,11 @@ The package system uses a signature mech
> > >  is fully identified by its package names, plus the dependencies against
> > >  which it was built, plus the version numbers of all shared libraries it
> > >  contains.
> >
> > I'd be tempted to leave this as is, or only add something like what you
> > propose below.  I'm not objecting though.  :)
>
> I've kept it for now, but not sure it adds much ...
>
> >
> > > +
> > > +<li>
> > > +The version comparison ordering can be summarized as:
> > > +<code>0.1 &lt; 0.1p0 &lt; 0.2 &lt; 0.1v0 &lt; 0.1p0v0 &lt; 0.2v0 &lt; 0.1v1</code>.
> > > +Check packages-specs(7) for more detailed information.
> > >  </ul>
>
> This is the sentence that triggered all this.  I kind of like how visual
> it is, so I would keep it.
>
> Cheers,
>
> --
> Paco Esteban.
> 0x5818130B8A6DBC03

> Index: bsd.port.mk.5
> ===================================================================
> RCS file: /home/cvs/src/share/man/man5/bsd.port.mk.5,v
> retrieving revision 1.528
> diff -u -p -r1.528 bsd.port.mk.5
> --- bsd.port.mk.5 24 Mar 2020 14:59:52 -0000 1.528
> +++ bsd.port.mk.5 26 Mar 2020 09:06:35 -0000
> @@ -1650,6 +1650,10 @@ If set to
>  will not open changed files in an editor.
>  .It Ev EPOCH
>  Epoch number of the current package.
> +Used when the port version is changed but the new version is not regarded by
> +.Xr packages-specs 7
> +as being newer.
> +Once added, it cannot be removed or go backwards.
>  Defaults to empty (no need for numbering changes), then
>  numbering starts at 0.
>  Gets automatically incorporated into

> Index: packages-specs.7
> ===================================================================
> RCS file: /home/cvs/src/share/man/man7/packages-specs.7,v
> retrieving revision 1.25
> diff -u -p -r1.25 packages-specs.7
> --- packages-specs.7 27 Oct 2014 22:45:30 -0000 1.25
> +++ packages-specs.7 26 Mar 2020 09:20:10 -0000
> @@ -144,15 +144,20 @@ then normal version, and finally
>  .El
>  .El
>  .Pp
> -In some rare cases, version numbering changes completely upstream.
> +In some rare cases, a change to a port would cause the version number to
> +compare as older than the previous version.
> +This happens if an update is reverted, if upstream's numbering scheme changes
> +completely, or if their usual scheme does not align with the one used by
> +.Ox .
>  A version style marker, of the form
>  .Sq v0 ,
>  .Sq v1 ...
>  can be appended to the version number (after the patch level)
>  to denote the new numbering scheme.
> -See
> +This marker is added by setting
>  .Ev EPOCH
> -in
> +in the port Makefile and it takes precedence over the regular package version.
> +See
>  .Xr bsd.port.mk 5 .
>  .Pp
>  Flavored packages will also contain a list of flavors after the version

> Index: faq/ports/guide.html
> ===================================================================
> RCS file: /home/cvs/www/faq/ports/guide.html,v
> retrieving revision 1.89
> diff -u -p -r1.89 guide.html
> --- faq/ports/guide.html 28 Sep 2019 21:35:05 -0000 1.89
> +++ faq/ports/guide.html 26 Mar 2020 09:15:43 -0000
> @@ -1138,6 +1138,8 @@ If something unexpected happens and you
>  upstream numbering changes completely so that the version number appears
>  to go backwards, you must use <code>EPOCH</code> to make sure pkg_add(1) sees
>  the package as a newer package.
> +This will add <code>v${EPOCH}</code> to <code>FULLPKGNAME</code> to form a full
> +package-name conforming to packages-specs(7).
>  
>  <li>
>  If the package does not build, no bump is needed: changes to restore a port
> @@ -1153,6 +1155,11 @@ The package system uses a signature mech
>  is fully identified by its package names, plus the dependencies against
>  which it was built, plus the version numbers of all shared libraries it
>  contains.
> +
> +<li>
> +The version comparison ordering can be summarized as:
> +<code>0.1 &lt; 0.1p0 &lt; 0.2 &lt; 0.1v0 &lt; 0.1p0v0 &lt; 0.2v0 &lt; 0.1v1</code>.
> +Check packages-specs(7) for more detailed information.
>  </ul>
>  
>  Part of the work will happen before the update itself.

Good enough for me, go for it.
There will probably be minor tweaks after the fact by our native speaker. :)

Reply | Threaded
Open this post in threaded view
|

Re: clarification of REVISION and EPOCH documentation.

Jeremie Courreges-Anglas-2
On Thu, Mar 26 2020, Marc Espie <[hidden email]> wrote:

[...]

> Good enough for me, go for it.

Yep.  Thanks a lot for improving those items!
ok jca@

> There will probably be minor tweaks after the fact by our native speaker. :)

We need more of those.  8)

--
jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF  DDCC 0DFA 74AE 1524 E7EE