Make GitHub sub-versions (revisions) be reflected in PORTVERSION

[yuri]

Summary

Currently, when port version is set to a GitHub sub-version (ex. DISTVERSION=1.0.0-35), PORTVERSION becomes 1.0.0.35 which
presents users with a version number that hasn't been defined by the project (1.0.0.35). The project only defined 1.0.0.

On the other hand, sub-versions are often necessary either because released versions don't build for various reasons, or because
fixes that were committed later need to be included, or simply because some projects just stop making releases, or don't make them
for a very long time.

To solve this, the attached patch adds a letter 'm' to the revision part of the PORTVERSION, making PORTVERSION=1.0.0.m35, for the above example.

This would be beneficial for all users, and also particularly for repology, because it primarily needs to know versions that FreeBSD ports are for, to
be able to compare version numbers with versions that other systems have.

[antoine]

Please follow the porters handbook, there is no need for additional change.

[yuri]

Using Github-derived sub-revision number has its benefit, though. It shows how many commits the revision is past the release. It amends the revision with a meaningful information that blends nicely with the release version number.
Besides, the approach with a date (X.X.X.a.20190320) has a problem that it can be done only once a day. It provides no way for the revision to be corrected during the same day without setting a wrong, made up date.

[antoine]

https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-distfiles.html#makefile-master_sites-github-ex5

[yuri]

Sections Example 5.11. More Complete Use of USE_GITHUB and Example 5.14. Using USE_GITHUB to Access a Commit Between Two Versions describe the same situation and provide different solutions (contradict each other because solutions are different). My patch refers to Example 5.14 which IMO is a superior solution. The patch makes it work nicely with outside users.

[yuri]

.

[mat]

In D19664#420928, @yuri wrote:

Using Github-derived sub-revision number has its benefit, though. It shows how many commits the revision is past the release. It amends the revision with a meaningful information that blends nicely with the release version number.
Besides, the approach with a date (X.X.X.a.20190320) has a problem that it can be done only once a day. It provides no way for the revision to be corrected during the same day without setting a wrong, made up date.

That is absolutely not true.

You can set g.20190320 And then with a later commit from that day g.20190320.1.

I don't see the point of this change, or what is better with it than with what was before.

When you do, as is documented, something like this:

DISTVERSIONPREFIX=  v
DISTVERSION=	0.7.3-14
DISTVERSIONSUFFIX=  -gf0038b1

The ONLY bit that is read by Git is the part after -g, and it is the commit hash. If you want to make it show that that it is not, in fact, 0.7.3.14 but, say, the 14th patch after, write 0.7.3p14 (which is after 0.7.3 and before 0.7.4) then simply write that (using PORTVERSION).

[yuri]

In D19664#422964, @mat wrote:

DISTVERSIONPREFIX=  v
DISTVERSION=	0.7.3-14
DISTVERSIONSUFFIX=  -gf0038b1

The ONLY bit that is read by Git is the part after -g, and it is the commit hash. If you want to make it show that that it is not, in fact, 0.7.3.14 but, say, the 14th patch after, write 0.7.3p14 (which is after 0.7.3 and before 0.7.4) then simply write that (using PORTVERSION).

When I set DISTVERSION=1.16.3-p363 in net-im/qTox, it fails to fetch it:

fetch: http://distcache.FreeBSD.org/ports-distfiles/qTox-qTox-v1.16.3-p363-gbef9d4b7_GH0.tar.gz: Not Found

So it DOES matter what DISTVERSION is supplied.

[mat]

In D19664#424862, @yuri wrote:

When I set DISTVERSION=1.16.3-p363 in net-im/qTox, it fails to fetch it:

fetch: http://distcache.FreeBSD.org/ports-distfiles/qTox-qTox-v1.16.3-p363-gbef9d4b7_GH0.tar.gz: Not Found

So it DOES matter what DISTVERSION is supplied.

This is the *distcache*, it only gets filed by a cron on the cluster, so a file won't happen there before a port update get committed.

I'm going to revise what I said earlier, in v1.16.3-363-gbef9d4b7, git only cares about the part after -g, you can write it foo.bar-gbef9d4b7, it seems github works differently, only the first part is completely ignored, the second part, even if it is ignored in the end, has to be numeric, and it only uses the hash after -g.

[yuri]

In D19664#424949, @mat wrote:

This is the *distcache*, it only gets filed by a cron on the cluster, so a file won't happen there before a port update get committed.

I'm going to revise what I said earlier, in v1.16.3-363-gbef9d4b7, git only cares about the part after -g, you can write it foo.bar-gbef9d4b7, it seems github works differently, only the first part is completely ignored, the second part, even if it is ignored in the end, has to be numeric, and it only uses the hash after -g.

I think documentation should be updated and it should say what DISTVERSION should be set to in this situation, because leaving it in the numeric format like this upsets repology.

[mat]

In D19664#424953, @yuri wrote:

In D19664#424949, @mat wrote:

This is the *distcache*, it only gets filed by a cron on the cluster, so a file won't happen there before a port update get committed.

I'm going to revise what I said earlier, in v1.16.3-363-gbef9d4b7, git only cares about the part after -g, you can write it foo.bar-gbef9d4b7, it seems github works differently, only the first part is completely ignored, the second part, even if it is ignored in the end, has to be numeric, and it only uses the hash after -g.

I think documentation should be updated and it should say what DISTVERSION should be set to in this situation, because leaving it in the numeric format like this upsets repology.

Example 5.14 already explains how this works. If whatever repology is has bugs, please fix repology, the ports tree works just fine as it is.

[yuri]

In D19664#425006, @mat wrote:

Example 5.14 already explains how this works. If whatever repology is has bugs, please fix repology, the ports tree works just fine as it is.

Example 5.14 leads to version concatenation, which makes patch revisions indistinguishable from regular versions. For example, it produces the version 0.7.3.14, there's no way to tell that .14 results from the patch level. Repology can't be "fixed" to distinguish such versions.
The example should be modified to something like DISTVERSION= 0.7.3-p-14 so that PORTVERSION would become 1.16.3.p.363. It should be done the same way for all such versions, hence the example change should direct people to how it should be done. The current example leads to the confusion with versions.

[AMDmi3]

Example 5.14 already explains how this works. If whatever repology is has bugs, please fix repology, the ports tree works just fine as it is.

There's no bug in repology, there's bug in 5.14, because it makes a number of commits past the upstream version look like the part of it.

% make -C /usr/ports/math/bcal -V DISTVERSION -V PORTVERSION -V PKGNAME
2.1-12
2.1.12
bcal-2.1.12

This clearly looks as bcal version 2.1.12 to any package user, with no way to know it's actually a 12th commit past 2.1, and not a real version.
This is POLA violation and a source of confusion, as versions are used by humans and not just pkg version, in web and documentation searches, submitting bug reports, comparing to upstream etc, and referring to non-existing product versions lead to failures in these activities.
The fact that repology can't handle these versions properly is just the consequence of their brokenness for everybody. It can't be fixed in repology, as there's no way to tell fake 2.1.12 from genuine 2.1.12 just by looking at version.

Another problem of this scheme is that an upstream may do a patch release. For above example it could be 2.1.1. Since it's lesser than already used 2.1.12 it would leave no other option than to do a PORTEPOCH bump which we all don't like.

Yet another, more serious problem is that versions are also used for security purposes, e.g. in CPE and vuxml matching. So in the case of vulnerability discovered for bcal <= 2.1, fake 2.1.12 won't match, it won't be reported leaving the system vulnerable.

IMO just incrementing PORTREVISION for snapshots is sufficient, correct and consistent. Technically, it's just a set of patches.

Using explicit suffix (like gitYYYYMMDD or gitXX) could work too, as it's at least explicit and does not lead to confusion. But the problem of losing upstream version still remains, and there's always a problem of comparing X.Y.gitZ, X.YgitZ, and X.Y - different consumers may have different opinions on which are equal and which is greater.

So I suggest to rewrite

PORTNAME=	bar
DISTVERSIONPREFIX=  v
DISTVERSION=	0.7.3-14
DISTVERSIONSUFFIX=  -gf0038b1

USE_GITHUB=	yes

as

PORTNAME=	bar
DISTVERSIONPREFIX=  v
DISTVERSION=	0.7.3
DISTVERSIONSUFFIX=  -14-gf0038b1
PORTREVISION=   1

USE_GITHUB=	yes

[AMDmi3]

@yuri, note that there's no way to solve this with a patch to Mk anyway, as it would make bunch of versions go backwards. All ports using this scheme can only be fixed by updating to next upstream version as soon as it's released, and dropping git suffix, or by bumping PORTEPOCH which is discouraged