Re: clarification of REVISION and EPOCH documentation.
On Thu, Mar 26 2020, Marc Espie wrote: [...] > Good enough for me, go for it. Yep. Thanks a lot for improving those items! ok jca@ > There will probably be minor tweaks after the fact by our native speaker. :) We need more of those. 8) -- jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF DDCC 0DFA 74AE 1524 E7EE
Re: clarification of REVISION and EPOCH documentation.
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 - 1.528
> > > +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -
> > > @@ -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 - 1.89
> > > +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -
> > > @@ -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 REVISION if already present, otherwise
> > > adding
> > > REVISION = 0 towards the top of the Makefile.
> > > +This will add p${REVISION} to FULLPKGNAME to
> > > form a full
> > > +package-name conforming to packages-specs(7).
>
> This is wrong, not sure how it get there. I removed it.
>
> > >
> > > 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 EPOCH to make sure pkg_add(1)
> > > sees
> > > the package as a newer package.
> > > +This will add v${EPOCH} to FULLPKGNAME to form
> > > a full
> > > +package-name conforming to packages-specs(7).
> > >
> > >
> > > 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
Re: clarification of REVISION and EPOCH documentation.
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 - 1.528
> > +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -
> > @@ -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.html28 Sep 2019 21:35:05 - 1.89
> > +++ faq/ports/guide.html14 Mar 2020 14:39:36 -
> > @@ -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 REVISION if already present, otherwise adding
> > REVISION = 0 towards the top of the Makefile.
> > +This will add p${REVISION} to FULLPKGNAME to
> > form a full
> > +package-name conforming to packages-specs(7).
This is wrong, not sure how it get there. I removed it.
> >
> > 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 EPOCH to make sure pkg_add(1)
> > sees
> > the package as a newer package.
> > +This will add v${EPOCH} to FULLPKGNAME to form a
> > full
> > +package-name conforming to packages-specs(7).
> >
> >
> > 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 ...
>
> >
Re: clarification of REVISION and EPOCH documentation.
On Wed, Mar 25 2020, Paco Esteban wrote:
> On Sun, 15 Mar 2020, Marc Espie wrote:
>
>> On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
>> > 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 ??
>>
>> Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
>> and tweaking _print-metadata, so we didn't hav to change every
>> dependent port.
>>
>> You still need to bump REVISION in dependent port when you change PKGSPEC
>> though.
>
> Thanks Marc, I tried to include that too.
> All patches updated and attached again.
>
> Cheers,
Comments inline,
> 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 - 1.528
> +++ bsd.port.mk.5 25 Mar 2020 20:07:07 -
> @@ -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
> +as being newer.
> +Once added, it cannot be removed or go backwards.
otherwise, ok jca@ for this hunk
> 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.
> .It Ev ERRORS
> List of errors found while parsing the port's Makefile.
> Display the errors before making any target, and if any error starts with
>
> [3. text/plain; packages-specs.diff]
> 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 - 1.25
> +++ packages-specs.7 15 Mar 2020 11:25:27 -
> @@ -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 .
ok jca@ for this hunk
> 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?
> See
> .Ev EPOCH
> in
>
> [4. text/plain; ports-guide.diff]
> 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 - 1.89
> +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -
> @@ -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 REVISION if already present, otherwise adding
> REVISION = 0 towards the top of the Makefile.
> +This will add p${REVISION} to FULLPKGNAME to form
> a full
> +package-name conforming to packages-specs(7).
>
>
> 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
Re: clarification of REVISION and EPOCH documentation.
On Wed, Mar 25, 2020 at 09:11:14PM +0100, Paco Esteban wrote: > On Sun, 15 Mar 2020, Marc Espie wrote: > > > On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote: > > > 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 ?? > > > > Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk > > and tweaking _print-metadata, so we didn't hav to change every > > dependent port. > > > > You still need to bump REVISION in dependent port when you change PKGSPEC > > though. > > Thanks Marc, I tried to include that too. > All patches updated and attached again. Oh sorry, I only intended to explain the history of things. I think that PKGSPEC is too much detail in the documentation. It's still supposed to be a reference manual, this does not belong in the man page, possibly in the web page, but this will turn people away from the manpage.
Re: clarification of REVISION and EPOCH documentation.
On Sun, 15 Mar 2020, Marc Espie wrote:
> On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote:
> > 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 ??
>
> Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk
> and tweaking _print-metadata, so we didn't hav to change every
> dependent port.
>
> You still need to bump REVISION in dependent port when you change PKGSPEC
> though.
Thanks Marc, I tried to include that too.
All patches updated and attached again.
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 - 1.528
+++ bsd.port.mk.5 25 Mar 2020 20:07:07 -
@@ -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
+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
@@ -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.
.It Ev ERRORS
List of errors found while parsing the port's Makefile.
Display the errors before making any target, and if any error starts with
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.727 Oct 2014 22:45:30 - 1.25
+++ packages-specs.715 Mar 2020 11:25:27 -
@@ -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.html28 Sep 2019 21:35:05 - 1.89
+++ faq/ports/guide.html14 Mar 2020 14:39:36 -
@@ -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 REVISION if already present, otherwise adding
REVISION = 0 towards the top of the Makefile.
+This will add p${REVISION} to FULLPKGNAME to form a
full
+package-name conforming to packages-specs(7).
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 EPOCH to make sure pkg_add(1) sees
the package as a newer package.
+This will add v${EPOCH} to FULLPKGNAME to form a full
+package-name conforming to packages-specs(7).
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.
+
+
+The version comparison ordering can be summarized as:
+0.1 0.1p0 0.2 0.1v0 0.1p0v0 0.2v0
0.1v1.
+Check packages-specs(7) for more detailed information.
Part of the work will happen before the update itself.
Re: clarification of REVISION and EPOCH documentation.
On Sun, Mar 15, 2020 at 12:28:25PM +0100, Paco Esteban wrote: > 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 ?? Yes, that's the main reason that led to introducing PKGSPEC in bsd.port.mk and tweaking _print-metadata, so we didn't hav to change every dependent port. You still need to bump REVISION in dependent port when you change PKGSPEC though.
Re: clarification of REVISION and EPOCH documentation.
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 - 1.527
> > +++ bsd.port.mk.5 14 Mar 2020 14:46:18 -
> > @@ -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.727 Oct 2014 22:45:30 - 1.25
> > +++ packages-specs.714 Mar 2020 15:00:42 -
> > @@ -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 - 1.527
+++ bsd.port.mk.5 15 Mar 2020 11:03:12 -
@@ -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.727 Oct 2014 22:45:30 - 1.25
+++ packages-specs.715
Re: clarification of REVISION and EPOCH documentation.
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 - 1.527
> +++ bsd.port.mk.5 14 Mar 2020 14:46:18 -
> @@ -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 - 1.25
> +++ packages-specs.7 14 Mar 2020 15:00:42 -
> @@ -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 - 1.89
> +++ faq/ports/guide.html 14 Mar 2020 14:39:36 -
> @@ -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 REVISION if already present, otherwise adding
> REVISION = 0 towards the top of the Makefile.
> +This will add p${REVISION} to FULLPKGNAME to form
> a full
> +package-name conforming to packages-specs(7).
>
>
> 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 EPOCH to make sure pkg_add(1) sees
> the package as a newer package.
> +This will add v${EPOCH} to FULLPKGNAME to form a
> full
> +package-name conforming to packages-specs(7).
>
>
> 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
