clarification of REVISION and EPOCH documentation.

[Paco Esteban]

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.
 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    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.
 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.
+Combined with
+.Ev REVISION ,
+this leaves the version ordering as follows:
+.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.