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 < 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.
