Re: Fix mk/fetch/github.mk

[Greg Troxel <gdt%lexort.com@localhost>]

Adam <adam%netbsd.org@localhost> writes:

> Attaching a version that introduces GITHUB_REF. This also requires a
> change in mk/fetch/bsd.fetch-vars.mk (GITHUB_TAG -> GITHUB_REF in line
> 52).

Is REF supposed to mean "sha-1 commit hash".  I realize I'm complaining
about names, but with git, ref is a broad term that include branches,
tags, and commit hashes.

> From what I see, there's too much magic happening at
> https://github.com/OWNER/REPO/archive end-point. I can't find its
> description in the REST API guide
> https://docs.github.com/en/rest?apiVersion=2022-11-28, or maybe I'm
> too tired to see. So, I suggest we stick to the documented API, or
> some unexpected things might happen like the one I've encountered with
> libproxy.

Given the widespread use of hashes in GITHUB_TAG and the use of
refs/tags/foo, it seems there is some solid behavior.

What I don't understand is why a GITHUB_TAG of just a tag vN.M, vs
refs/tags/vN.M, ever works.  Does it?   Before the recent changes, did
things mostly work?


> # DISTNAME=	exampleproject-1.2
> # MASTER_SITES=	${MASTER_SITE_GITHUB:=accountname/}
> #
> # The following variables alter github.mk behavior:
> #
> # GITHUB_PROJECT	defaults to PKGBASE
> # GITHUB_TAG		defaults to PKGVERSION_NOREV
> #			sometimes you want to override with v${PKGVERSION_NOREV}
> #			SHA-1 commit ids are also acceptable
> # GITHUB_RELEASE	defaults to not defined, set this to ${DISTNAME}
> #			when packaging a release not based on a git tag.
> # GITHUB_SUBMODULES	manually set submodule information:
> #			values should be:
> #			GitHub_user GitHub_project tag_or_hash submodule_path
> # GITHUB_TYPE		overrides the autodetected MASTER_SITE URL scheme:

> # "tag"
> # This is the default when GITHUB_RELEASE is not defined. Example URL:
> # http://github.com/acct/${GITHUB_PROJECT}/archive/{GITHUB_TAG}.tar.gz
> #
> # "release"
> # This is the default when GITHUB_RELEASE is set. Example URL:
> # http://github.com/acct/${GITHUB_PROJECT}/releases/download/${GITHUB_RELEASE}/${DISTNAME}.tar.gz
> #
> # Keywords: github

It's really hard to review changes without the documentation being
changed too.  The definition of intended semantics and guidance to users
is important.

> .  if ${GITHUB_TYPE} == release
> SITES.${_GITHUB_DEFAULT_DISTFILES}=	${MASTER_SITES:=${GITHUB_PROJECT}/releases/download/${GITHUB_RELEASE}/}
> .  elif ${GITHUB_TYPE} == ref
> SITES.${_GITHUB_DEFAULT_DISTFILES}=	-${MASTER_SITES:=${GITHUB_PROJECT}/tarball/${GITHUB_REF}}
> .  elif ${GITHUB_TYPE} == tag
> SITES.${_GITHUB_DEFAULT_DISTFILES}=	-${MASTER_SITES:=${GITHUB_PROJECT}/archive/refs/tags/${GITHUB_TAG}${EXTRACT_SUFX}}
> .  endif

It looks like tarball takes an arbitrary git ref but I find the docs
unclear.

https://docs.github.com/en/rest/repos/contents?apiVersion=2022-11-28


Even if the current API blurs commit hashes and tags, it may be best to
document two variables, one for each, so that we can adapt to future API
changes.