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 < 0.1p0 < 0.2 < 0.1v0 < 0.1p0v0 < 0.2v0 <
> > 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 < 0.1p0 < 0.2 < 0.1v0 < 0.1p0v0 < 0.2v0 <
0.1v1</code>.
+Check packages-specs(7) for more detailed information.
</ul>
Part of the work will happen before the update itself.
