[RFE] Please add a standard ref object to releases

[RFE] Please add a standard ref object to releases

[Nicolas Mailhot]

Hi,

git makes no provision for versioned release references.

However, software projects need versioned releases. Software project
integrators need versionned releases. Security auditors need versioned
release. Software project users need versioned releases.

Versioned releases are not the same thing as free-form tags. They have
semantics to allow deducing upgrade paths (usually, a form of semver).
They imply some form of API stability promise. They imply release
documentation completion. They're not just a random point in the project
history like tags are.

This is why most git hosting sites provide a way to select versioned
releases, even if it's not a native git concept. And this way is clearly
separate and distinct from git tag selection.

Unfortunately, since git makes no provision for versioned release
references, git hosting sites have to shove release refs into tag refs.
And it's a huge mess.

Some put release ids in tags as-is, others add a v prefix, others a
version_ prefix, it's all hoster-specific, it's all inconsistent. It
ends up being inconsistent within projects, as they migrate from a
hoster to another, are mirrored from one hoster to another. It depends
on the habits of the person cutting a release, and the release manager
of a project can change over time. It ends up being inconsistent in
release archives, as the version munging can percolate in the archive
name and structure, or not, for mysterious heuristic reasons that change
over time.

As a result, when assembling a project that uses other git repositories,
you spend more time checking repository by repository and version by
version how the version ref was mangled in a tag ref for this specific
(repo,version,date) tuple, than doing actual software dev and QA work.

Please add a specific release reference to git, so software projects
that do versioned releases can use this ref object directly, without
needing to invent custom version rewriting rules to shove them in tags
while marking they are not just tags but release references.

Regards,


-- 
Nicolas Mailhot

Re: [RFE] Please add a standard ref object to releases

[Ævar Arnfjörð Bjarmason]

On Thu, Nov 01 2018, Nicolas Mailhot wrote:

> git makes no provision for versioned release references.
>
> However, software projects need versioned releases. Software project
> integrators need versionned releases. Security auditors need versioned
> release. Software project users need versioned releases.
>
> Versioned releases are not the same thing as free-form tags. They have
> semantics to allow deducing upgrade paths (usually, a form of semver).
> They imply some form of API stability promise. They imply release
> documentation completion. They're not just a random point in the project
> history like tags are.
>
> This is why most git hosting sites provide a way to select versioned
> releases, even if it's not a native git concept. And this way is clearly
> separate and distinct from git tag selection.
>
> Unfortunately, since git makes no provision for versioned release
> references, git hosting sites have to shove release refs into tag refs.
> And it's a huge mess.
>
> Some put release ids in tags as-is, others add a v prefix, others a
> version_ prefix, it's all hoster-specific, it's all inconsistent. It
> ends up being inconsistent within projects, as they migrate from a
> hoster to another, are mirrored from one hoster to another. It depends
> on the habits of the person cutting a release, and the release manager
> of a project can change over time. It ends up being inconsistent in
> release archives, as the version munging can percolate in the archive
> name and structure, or not, for mysterious heuristic reasons that change
> over time.
>
> As a result, when assembling a project that uses other git repositories,
> you spend more time checking repository by repository and version by
> version how the version ref was mangled in a tag ref for this specific
> (repo,version,date) tuple, than doing actual software dev and QA work.
>
> Please add a specific release reference to git, so software projects
> that do versioned releases can use this ref object directly, without
> needing to invent custom version rewriting rules to shove them in tags
> while marking they are not just tags but release references.

For both this and your other report, it would be helpful if you describe
in concrete terms (with examples of git commands, or UI etc.) what git
commands do now, what's wrong with it, and some sketch of what you
expect an alternate interface to look like.

As for this report: I know this area of git quite well, but I still have
no idea quite what you're asking for.

Do you just mean that we should have some other second-level namespace
for tags, i.e. in addition to refs/tags/* we'd have
refs/this-time-I-really-meant-it-tags/*., and e.g. linux.git and git.git
v* tags would go into that, and have some "git tag --i-really-mean-it"
interface?

If we assume this is a good idea, how do you imagine this would work
once you don't just have two levels (random labels v.s. "real" releases)
but three or more (random labels v.s. "real" releases v.s. "LTS"
releases, ....)?

Re: [RFE] Please add a standard ref object to releases

[Nicolas Mailhot]

Le jeudi 01 novembre 2018 à 12:15 +0100, Ævar Arnfjörð Bjarmason a
écrit :
> 
> For both this and your other report, it would be helpful if you
> describe
> in concrete terms (with examples of git commands, or UI etc.) what git
> commands do now, what's wrong with it, and some sketch of what you
> expect an alternate interface to look like.
> 
> As for this report: I know this area of git quite well, but I still
> have no idea quite what you're asking for.

It says a lot that you claim to know this area of git quite well, but
have no understanding how it is (mis)used on github/gitlab/bitbucket/etc
by people who actually try to use git.

I’m just asking that when a project releases “x.y.z”

1. there was a standard git command available to it to create "the
release “x.y.z”" ref

2. there was a git syntax to say "the release “x.y.z”" ref in all git
commands that manipulate refs

3. that this "release “x.y.z”" ref could be used in all the "download
release “x.y.z”" on GitLab/GitHub, etc

4. that there was no fuziness or human interpretation involved into
converting "x.y.z" into the syntax used to select "release “x.y.z”" in
git commands

5. there was no ambiguïty in this syntax that led to the selection of
things that are not "release" refs and just look like them

And **not** the current situation where there are no official "release
ref" objects and "just map release names to tags, mapping recipe is left
to the reader". Because everyone invents its own recipe and the result
does not work.

And no, vfoo is not a form of release ref, because v1 can be a branch,
not a tag, version3 tag is not the release ersion3, etc (real-world
examples I can provide links if you don't believe me). You can’t let
things undefined as they are now because git users as a whole are making
a mess of things without tooling help.

> If we assume this is a good idea, how do you imagine this would work
> once you don't just have two levels (random labels v.s. "real"
> releases)
> but three or more (random labels v.s. "real" releases v.s. "LTS"
> releases, ....)?

IMHO you’re over-engineering things there. There is a need for separate
release refs, as evidenced by the fact every major git web frontend had
to separate them from normal tags in its UI. I'm not aware of the same
thing for LTS or whatever.

Of course implementing generic namespacing, would be a way to get a
separate release namespace. As long as this release namespace is
unambiguously defined at the git level without replaying the 'just
invent your own tag recipe' mess at another level.

Regards,

-- 
Nicolas Mailhot

Re: [RFE] Please add a standard ref object to releases

[Ævar Arnfjörð Bjarmason]

On Thu, Nov 01 2018, Nicolas Mailhot wrote:

> Le jeudi 01 novembre 2018 à 12:15 +0100, Ævar Arnfjörð Bjarmason a
> écrit :
>>
>> For both this and your other report, it would be helpful if you
>> describe
>> in concrete terms (with examples of git commands, or UI etc.) what git
>> commands do now, what's wrong with it, and some sketch of what you
>> expect an alternate interface to look like.
>>
>> As for this report: I know this area of git quite well, but I still
>> have no idea quite what you're asking for.
>
> It says a lot that you claim to know this area of git quite well, but
> have no understanding how it is (mis)used on github/gitlab/bitbucket/etc
> by people who actually try to use git.

Yeah I think it says a lot about how vague your proposal is.

You're the one trying to ostensibly file some sort of bug report or
feature request, it's up to you to explain the problem in detail.

> I’m just asking that when a project releases “x.y.z”
>
> 1. there was a standard git command available to it to create "the
> release “x.y.z”" ref

And would these also be annotated tags, or are you proposing that we add
a new "release" object type in addition to blob/tree/commit/tag? If so
what would that look like?

> 2. there was a git syntax to say "the release “x.y.z”" ref in all git
> commands that manipulate refs

What do you mean "git syntaX"? The rev-parse syntax (see 'git help
rev-parse`) or something else?

> 3. that this "release “x.y.z”" ref could be used in all the "download
> release “x.y.z”" on GitLab/GitHub, etc

So instead of offering a download of annotated tags as they do now, see
https://github.com/git/git/releases and
https://gitlab.com/git-vcs/git/tags they'd offer a download of whatevr
this new thing is?

> 4. that there was no fuziness or human interpretation involved into
> converting "x.y.z" into the syntax used to select "release “x.y.z”" in
> git commands

So since we'd store this in refs/* somewhere since it's (presumably)
named named ref of some sort, you're suggesting that this thing be
exempt from the DWYM name resolution of refs, e.g. us resolving "master"
to "refs/heads/master" or v1.0 to "refs/tags/v1.0" (but as you note
that's ambiguous).

So you'd always need to do e.g. "git show refs/releases/v1.0"?

> 5. there was no ambiguïty in this syntax that led to the selection of
> things that are not "release" refs and just look like them

I don't know what you mean by "syntax" and "selection" in this context.

> And **not** the current situation where there are no official "release
> ref" objects and "just map release names to tags, mapping recipe is left
> to the reader". Because everyone invents its own recipe and the result
> does not work.

I'm still entirely unclear about "does not work" here.

> And no, vfoo is not a form of release ref, because v1 can be a branch,
> not a tag, version3 tag is not the release ersion3, etc (real-world
> examples I can provide links if you don't believe me). You can’t let
> things undefined as they are now because git users as a whole are making
> a mess of things without tooling help.

This seems like another complaint about the ref ambiguities. That's fair
enough, but how is that per-se related to this proposal? We also have
ambiguity now between "master" tags and branches.

>> If we assume this is a good idea, how do you imagine this would work
>> once you don't just have two levels (random labels v.s. "real"
>> releases)
>> but three or more (random labels v.s. "real" releases v.s. "LTS"
>> releases, ....)?
>
> IMHO you’re over-engineering things there. There is a need for separate
> release refs, as evidenced by the fact every major git web frontend had
> to separate them from normal tags in its UI. I'm not aware of the same
> thing for LTS or whatever.
>
> Of course implementing generic namespacing, would be a way to get a
> separate release namespace. As long as this release namespace is
> unambiguously defined at the git level without replaying the 'just
> invent your own tag recipe' mess at another level.

It's not over-engineering. Right now we have a hierarchical namespace
for tags and branches, so if you want N levels deep or whatever you do
that with prefixes or subdirectories, and there's plenty of examples of
that in the wild. E.g. tags created for hacking, QA, pre-release,
release, LTS etc.

Whereas if you're proposing some mechanism that we draw a line somewhere
in that flow and say "now tag/mark/release stuff as different sorts of
objects" it's up to you to convince us why that's a realistic view of
the world.

Re: [RFE] Please add a standard ref object to releases

[Nicolas Mailhot]

Le jeudi 01 novembre 2018 à 14:09 +0100, Ævar Arnfjörð Bjarmason a
é

> You're the one trying to ostensibly file some sort of bug report or
> feature request, it's up to you to explain the problem in detail.
> 
> > I’m just asking that when a project releases “x.y.z”
> > 
> > 1. there was a standard git command available to it to create "the
> > release “x.y.z”" ref
> 
> And would these also be annotated tags, or are you proposing that we
> add
> a new "release" object type in addition to blob/tree/commit/tag? If so
> what would that look like?

It could have been done via annotated tags if release annotations, and
the associated porcelain, had been clearly defined and documented from
the start up. The technical implementation would have been fuzzy but
strong convention would have compensated the fuzziness.

This ship sailed a long time ago, at this point not only you do not have
convention to help you but you have all the custom workarounds people
invented to get by to overcome. So, I doubt anything short of a separate
object can work now (but I'd be delighted to be proven wrong).

Of course as long as the porcelain is unambiguous most git users won't
care how it is stored by git.

> > 2. there was a git syntax to say "the release “x.y.z”" ref in all
> > git
> > commands that manipulate refs
> 
> What do you mean "git syntaX"? The rev-parse syntax (see 'git help
> rev-parse`) or something else?

I mean that:
– I give you a repo name and its URL.
– I give you a release name such as 1.2.3.4
 1. write the command to checkout this release
 2. write  the command to diff this release with the latest master
commit
 3. write  the command to declare that master is release 1.2.3.4.5
etc

You’re forbidden to look at the content of the repo to browse its tags
and branches and use human logic to guess human convention. You can only
be sure that 1.2.3.4 is the actual release chosen by the project owner
as stated in its release notes.

And then try to do it for Apache Thrift 0.11 and git 2.19.0
https://github.com/apache/thrift/
and
https://github.com/git/git

(see, I’m nice, I didn’t even fed you Gitlab vs GitHub differences, or
some project released by an illustrious anonymous)

Or alternatively, try
gnome-calendar 3.28.0.1 and git 2.18.1

They’re on
https://gitlab.com/git-vcs/git/
https://gitlab.gnome.org/GNOME/gnome-calendar/

so, latest version of Gitlab for both of them.

> > 3. that this "release “x.y.z”" ref could be used in all the
> > "download
> > release “x.y.z”" on GitLab/GitHub, etc
> 
> So instead of offering a download of annotated tags as they do now,
> see
> https://github.com/git/git/releases and
> https://gitlab.com/git-vcs/git/tags they'd offer a download of whatevr
> this new thing is?

So they could build a
https://github.com/git/git/releases/<x.y.z>/
or
https://gitlab.com/git-vcs/git/releases/<x.y.z>/

and it would just give you the correct release archive, for example. Not
difficult for them to do as long as the mapping from release name “x.y.z
” to git repo object is well defined.

> > 4. that there was no fuziness or human interpretation involved into
> > converting "x.y.z" into the syntax used to select "release “x.y.z”"
> > in git commands
> 
> So since we'd store this in refs/* somewhere since it's (presumably)
> named named ref of some sort, you're suggesting that this thing be
> exempt from the DWYM name resolution of refs, e.g. us resolving
> "master"
> to "refs/heads/master" or v1.0 to "refs/tags/v1.0" (but as you note
> that's ambiguous).
> 
> So you'd always need to do e.g. "git show refs/releases/v1.0"?

It would be nice to have something shorter to type, but the root problem
is the ambiguity and lack of definition of current git releases, so
something unambiguous trumps something short, but fuzzy.

And, in your example, the v is unnecessary.

The v was just shoved in tag names to try to distinguish releases. It
didn’t work. It would have worked if git had blocked any tag starting
with v that was not a release tag, and forbidden branches with a v name.
But that ship sailed a long time ago.

Years of workarounds have brainwashed you into thinking the v is
necessary. But, it does not exist outside git land. Or even in the
release notes filenames git releases itself
https://github.com/git/git/tree/master/Documentation/RelNotes

(Much as I hate the v thing, I could have lived with it if it was
consistently applied by git projects. It isn’t)

> Whereas if you're proposing some mechanism that we draw a line
> somewhere
> in that flow and say "now tag/mark/release stuff as different sorts of
> objects" it's up to you to convince us why that's a realistic view of
> the world.

If it was not a realistic view of the world github wouln’t have had to
define separate sections for releases and tags in its UI.

If tags and release were the same thing one could take random git
projects on github or gitlab and apply release rules like semver to
their tags. Even projects that use semver do not have semver-only tags,
and even their semver tags cant'd be semvered as-is because of random
injections of prefixes like v or version.

Regards,

-- 
Nicolas Mailhot