Consider adding release tags

[velovix]

With an official dependency management solution coming, I think it would be cool to see release tags on this repository. I'm not sure exactly how this should work, since this repository is already quasi-versioned with GLFW mainline. Perhaps what's here now could be tagged as v1.0.0 and the version number would only be bumped up when breaking changes or new features to existing bindings are introduced.

[dmitshur]

With an official dependency management solution coming, I think it would be cool to see release tags on this repository.

Can we wait until that solution comes out? As you said, the versioning for us is tricky, since it's tied to versions of GLFW upstream.

We don't yet know what requirements for the version numbers the dependency management solutions may require. Will it be semver? Will it be some variant thereof? How do the choices we make impact users? Etc.

I'd defer dealing with this until we have concrete reasons to do it, not speculative. As far as I know, there are no concrete benefits today, are there?

[velovix]

I think the piece of mind that versioning gives users and the added flexibility it gives maintainers is a concrete reason in and of itself.

On the more theoretical side, my concern is that taking the "wait and see" attitude towards versioning in Go is self-defeating. Dep (the solution I'm referring to) needs to be vetted by the community first before being officially added to the Go toolchain, but the community is discouraged from vetting Dep by repositories with no release tags.

As for the issue of versioning syntax, Dep uses semantic versioning and I don't know of any reason why that would change.

[dmitshur]

All right, I suppose I'm okay with doing it sooner then. I'm still not quite sold on the benefits, but if other people want this, I'm not against it.

We can use this issue to discuss and figure out what versioning system to use then.

GLFW itself seems to be using semver, but I'm not sure if we can use it directly, since there are some Go-specific changes in the API that may be independent of GLFW the C library's version. That said, using completely different version numbers may be confusing, especially since the major and minor version of GLFW are embedded in the import path of each glfw package.

One potential reference to look at is GopherJS, which is tied to Go minor versions. But the scheme GopherJS uses for its versions isn't semver. It's 1.x.y, where x is the Go minor version, and y is the GopherJS major version.

[tapir]

We're already only breaking API with GLFW minor versions. So I'm not sure what's the advantage of having a separate version number as git tags. It would only cause confusion I think. My proposal is to use GLFW versions as the tags.

[pwaller]

TL;DR: I think tags are a good idea. But go-gl/glfw needs to choose a tagging scheme, and there are a few things to consider and options available.

My thoughts on the matter (also #240):

To make using go-gl/glfw easier as a go module, I guess go-gl/glfw needs a tag. The question then becomes: what should the tag be? I guess that our tag needs to evolve independently of the glfw/glfw tag. In which case "v1.0" might be a reasonable tag, if people felt that the API was reasonably stable.

Another question on my mind is "How does the /v3.3/ in the go-glfw path interact with go mod's notion of major versions? Is there any conflict there?".

(Paraphrasing)

Master is quite stable, so grabbing a git sha and running with that isn't a big problem. Tags would be nice to have, though.

The obvious problem with tags is that the authors of go-gl/glfw might want to have tags of go-gl/glfw which do not appear in sync glfw/glfw. This could get confusing for users. Changing a published tag is not acceptable. But it might be necessary to fix a defect in the Go bindings for a specific glfw v3.3.x, for example. Say the repository was tagged as v3.3.0 with v3 as it is now, and then it was necessary to fix something. Do go-gl/glfw users not get the fix until upstream releases a tag with v3.3.1?

So here are some proposals, in no particular order.

A) Do nothing. Users grab a git sha and run with that.

• Pro: Easy for the maintainers.
• Con: Users see git sha's in their go.mod files
• Con: I'm unsure what the minimal-version selection algorithm does here - I assume it copes with this fine and picks the maximum of the minimum git shas in terms of their parent depth in the git commit tree. But that I even have to ask the question means that it's probably not obvious to users that this is a reasonable thing to do, even if it actually is.

B) Take the same tag as glfw.

• Pro: Conceptually fairly easy. Just one version number to worry about.
• Con: Can only make a release when upstream makes a release, otherwise it will be confusing.
  • Therefore: Users can only get a tagged bugfix when upstream makes a release.

C) Use a different tagging scheme than glfw

• Pro: Can make tags whenever.
• Con: Need to come up with a scheme everyone's happy with.
• Con: More than one version number to think about - both that of upstream glfw and of the go bindings.

D) Variant of B+C: Use the tag of glfw, but with abuse semantic versioning to put the binding version number in the build number or pre-release number

• Pro: potentially best of both worlds.
• Con: abuse of semver, might lead to confusion or issues (e.g. build number is mandated by semver spec to not be used to determine precedence).

If you have an opinion please comment and point towards your favourite :)

[golightlyb]

Have you considered keeping old-style GLFW-versioned folders, plus a "latest" folder that is both latest GLFW and latest Go bindings, which is then version tagged

[pwaller]

Have you considered keeping old-style GLFW-versioned folders, plus a "latest" folder that is both latest GLFW and latest Go bindings, which is then version tagged

Not sure I follow your suggestion or see what the benefits are. Could you elaborate?

One issue with my reading of your suggestion is that you imply that an individual folder might be tagged. Unfortunately the tags apply to the whole go-gl/glfw project, so the tags would apply to the other versions too.

[pchampio]

The obvious problem with tags is that the authors of go-gl/glfw might want to have tags of go-gl/glfw which do not appear in sync glfw/glfw. This could get confusing for users. Changing a published tag is not acceptable. But it might be necessary to fix a defect in the Go bindings for a specific glfw v3.3.x, for example. Say the repository was tagged as v3.3.0 with v3 as it is now, and then it was necessary to fix something. Do go-gl/glfw users not get the fix until upstream releases a tag with v3.3.1?

I don't think it will be confusing for users if we use multi-module-repositories.
The go.mod was carefully placed in the subdir v3.3/glfw instead of at the root of the repo.
Currently go.mod is currently looking like:

require (
	github.com/go-gl/glfw/v3.3/glfw v0.0.0-20191124195120-e5ec43523f6f
)

We have the version of glfw used (3.3) and the github tag / commit date-id of go-glfw.
If we tag the project with:

$ git tag v3.3/glfw/v1.0.0

the go.mod will look something like:

require (
	github.com/go-gl/glfw/v3.3/glfw v1.0.0
)

When knowing the root directory structure (v3.0/glfw v3.1/glfw v3.2/glfw v3.2/glfw v3.3/glfw) one can easily know that the version in the path correspond to the version of upstream GLFW.

The v1.0.0 can then be incremented without too much warring. (We can even start at v100.0.0 to avoid github.com/go-gl/glfw/v3.3/glfw v3.2.0 confusion).

I don't think we need to go down as having the <patch> number information of glfw. (Plus it is rarely used by them https://github.com/glfw/glfw/releases). The GLFW_C_REVISION.txt has this purpose.

Overall I'd say option (C).
The con:

Con: More than one version number to think about - both that of upstream glfw and of the go bindings.

Is already taking care by the version in the path and the GLFW_C_REVISION.txt file.

[pwaller]

Ah, neat, I wasn't aware that you could tag individual directories in that way. That sounds nice. Anyone else want to weigh in with an opinion? @tapir? Should we just go for it and tag /v3.3/ directory with v1.0? :)

I guess so long as we don't break the API, we could bump the patch version whenever GLFW_C_REVISION is updated.

I don't see any downsides to this, other than that it requires some work, but I suspect we can find some willing volunteers :)

[pwaller]

Thinking about it: The only reason to hold of from this is if we think we might want to do an (now urgent because it is in the wild) API break to fix a niggle in v3.3 before it gets wide use, if there are any.

[pchampio]

Thinking about it: The only reason to hold of from this is if we think we might want to do an (now urgent because it is in the wild) API break to fix a niggle in v3.3 before it gets wide use, if there are any.

If everyone is ok, we should go for v3.3/glfw/v1.0.0-alpha!

[pwaller]

If everyone is ok, we should go for v3.3/glfw/v1.0.0-alpha

Sounds good to me.

Any objections from anyone?

/cc @tapir @dmitshur @slimsag @hajimehoshi.

[hajimehoshi]

I'm fine, but when do we make v1.0.0?

[dmitshur]

I've never attempted to apply semver on top of another project with semver, so it's unexplored territory for me. I don't have strong objections to trying it, and going with the proposed scheme seems reasonable to me.

One thing to keep in mind is after we make the very first tagged release (or pre-release), we will need to keep that up for the lifetime of that module. It's not a decision we can ever revert.

The v1.0.0 can then be incremented without too much warring. (We can even start at v100.0.0 to avoid github.com/go-gl/glfw/v3.3/glfw v3.2.0 confusion).

This part isn't true. All major versions other than v0 and v1 require a /vN suffix. So v100.0.0 would require the import path to become github.com/go-gl/glfw/v3.3/glfw/v100. See https://blog.golang.org/v2-go-modules.

[dmitshur]

A small suggestion is to start with v0.1.0-alpha first, before getting to v1.0.0. We can always get to v1 after some time passes. The advantage of v0 is that it still permits breaking changes and gives us more time to learn about this process.

[hajimehoshi]

Oh, would it still be possible to add some breaking change to go-gl/glfw? Then v0.x would make sense.

[dmitshur]

We probably wouldn't, but given we just released v3.3/glfw a few days ago, there's some small chance we will learn that some part of the new API has a problem and will need to be fixed.