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
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 15 Mar 2020 11:03:12 -0000
@@ -1632,6 +1632,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
+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 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 .
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
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 < 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.
