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 identif
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 g
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 Ma
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 dependenci
clarification of REVISION and EPOCH documentation.
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. 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.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. 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.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.