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 < 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.
Good enough for me, go for it.
There will probably be minor tweaks after the fact by our native speaker. :)
