Github versions

[Jason Bacon <outpaddling%yahoo.com@localhost>]

I'd like to propose some additions to the developer's guide regarding 
Github repos:

    https://www.netbsd.org/docs/pkgsrc/fixes.html#build.fetch.github

Currently, the only example using a commit hash has a distname of 
"example-1.0" and does not indicate where the version 1.0 came from.  I 
propose splitting the section on use of commit hashes into two, 
corresponding to two possible states of the repository, and setting some 
conventions for package versions.  I'm open to suggestions for 
alternative version conventions as long as they ensure a correct 
sequence that uniquely identifies the Github commit and functions 
properly for package upgrades.

1) In the case where there have been no releases tagged on Github, it is 
important to choose a package version that will be "less than" a first 
release tag that might occur in the future.


       21.2.3.2. Fetch based on a specific commit where there have been
       no releases tagged

If your distfile is from a commit before the first release on Github, 
then set the package version to 0.0.0.N, where N is the number of 
commits to the repository, and GITHUB_TAG to the commit hash.  This will 
(almost) ensure that the first tagged release will have a version 
greater than this one so that package upgrades will function properly.

DISTNAME=       example-0.0.0.347
MASTER_SITES=   ${MASTER_SITE_GITHUB:=example/}
#GITHUB_PROJECT=        # can be omitted if same as DISTNAME
GITHUB_TAG=     988881adc9fc3655077dc2d4d757d480b5ea0e11


2) In the case of commits following a release, we can precisely and 
descriptively identify the commit by the last release and the number of 
commits since.  "git describe --tags" will show the last release 
followed by the # of commits since that release and the first 7 
characters of the hash, e.g.

# git describe --tags
0.6.3-4-gb20ce57


       21.2.3.3. Fetch based on a specific commit after a release

If your distfile is from a commit after a release, then include the last 
release version and the commit count since that release in the package 
version and set GITHUB_TAG to the commit hash.  The commit count is 
shown between the version and the commit hash in the output of "git 
describe --tags":

# git clone https://github.com/example/example
# cd example
# git describe --tags
1.2.3-5-g988881a

DISTNAME=       example-1.2.3.5
MASTER_SITES=   ${MASTER_SITE_GITHUB:=example/}
#GITHUB_PROJECT=        # can be omitted if same as DISTNAME
GITHUB_TAG=     988881adc9fc3655077dc2d4d757d480b5ea0e11