Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consider adding release tags #188

Open
velovix opened this issue Apr 5, 2017 · 21 comments
Open

Consider adding release tags #188

velovix opened this issue Apr 5, 2017 · 21 comments

Comments

@velovix
Copy link

velovix commented Apr 5, 2017

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
Copy link
Member

dmitshur commented Apr 5, 2017

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
Copy link
Author

velovix commented Apr 6, 2017

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
Copy link
Member

dmitshur commented Apr 6, 2017

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
Copy link
Member

tapir commented Aug 14, 2017

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 pwaller mentioned this issue Nov 24, 2019
@pwaller
Copy link
Member

pwaller commented Nov 24, 2019

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
Copy link

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
Copy link
Member

pwaller commented Nov 25, 2019

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
Copy link
Contributor

pchampio commented Nov 25, 2019

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
Copy link
Member

pwaller commented Nov 25, 2019

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
Copy link
Member

pwaller commented Nov 25, 2019

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
Copy link
Contributor

pchampio commented Nov 25, 2019

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
Copy link
Member

pwaller commented Nov 26, 2019

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
Copy link
Member

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

@dmitshur
Copy link
Member

dmitshur commented Nov 27, 2019

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
Copy link
Member

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
Copy link
Member

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

@dmitshur
Copy link
Member

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.

@Jacalz
Copy link
Collaborator

Jacalz commented Mar 6, 2024

I think this issue is a very nice idea for the project. We could stick to v0.X.Y releases where we update X when there are breaking changes or just large new work (such as v3.4 of glfw landing for example) and we update Y when there is minor work or an update to a new patch version of GLFW (such as v3.3.10). It looks a little cleaner in the module file and is just nicer overall than having to go to GitHub to check commit hashes.

@dmitshur
Copy link
Member

dmitshur commented Mar 6, 2024

Let's consider starting to do that in the new-to-be v3.4/glfw module (#393). What would some of the finer details look like? I wrote the following to try to answer that and explore options.

Its first release version can be v0.1.0. Note that the full tag name would be v3.4/glfw/v0.1.0 because it's a nested module. (We can do pre-release versions like v0.1.0-pre.{1,2,3,…} leading up to that, if desired.)

Suppose we bump the minor component after each update to a newer upstream GLFW release (like the ones done in PRs #396, #388, #361, etc.), or doing work involving glfw Go APIs (e.g., adding a new glfw Go API to expose some GLFW C API that wasn't already handled earlier).

What would do we in other cases? Consider a change like PR #387 or #391. If we don't create a tag but someone who wants to use the newer version that includes such a change, they would need to use a pseudo-version, or wait for the next tag to eventually happen, or file an issue requesting for it to happen sooner. Should we by default bump patch component (instead of minor component) in such cases? Do we exercise reasonable judgement to decide when to do it proactively and when not to?

It's worth also noting that typos or other such accidents can happen, especially if creating tags via a manual process, and fixing mistakes in pushed tags in the general case involves following the https://go.dev/blog/go116-module-changes#module-retraction process and ending up with a higher latest released version.

I think something like that can be workable. The additional work and risk involved is unfortunate, but I don't think it needs to block us from going ahead with it.

@Jacalz
Copy link
Collaborator

Jacalz commented Mar 7, 2024

Its first release version can be v0.1.0. Note that the full tag name would be v3.4/glfw/v0.1.0 because it's a nested module. (We can do pre-release versions like v0.1.0-pre.{1,2,3,…} leading up to that, if desired.)

I am not a fan of having the version as v3.4/glfw/v0.1.0. I think it is fine to have one version for the whole repository just like if it was a single module. You would not create individual releases for each package in that case. Also, importing the project as github.com/go-gl/glfw/v3.4/glfw v3.4/glfw/v0.1.0 in go.mod seems unnecessarily complex and just distracts form the actual v0.1.0 versions.

Also, I would be in favour of doing a v0.1.0 release right now and then a v0.2.0 when we have v3.4 in the repo.

What would do we in other cases? Consider a change like PR #387 or #391. If we don't create a tag but someone who wants to use the newer version that includes such a change, they would need to use a pseudo-version, or wait for the next tag to eventually happen, or file an issue requesting for it to happen sooner. Should we by default bump patch component (instead of minor component) in such cases? Do we exercise reasonable judgement to decide when to do it proactively and when not to?

I think it would be fair to bump the patch version number in that case. If there are multiple minor fixes coming in, we can of course batch them up into a patch release with more than one change. We don't necessarily have to create a new tag each time someone opens a PR. If the change is significant enough we can certainly do so as well.

@dmitshur
Copy link
Member

@Jacalz and I discussed #188 (comment) offline; I believe we agreed it's not something we can pursue in a way that works with the Go module system.

I still think #188 (comment) lets us move forward with gradually tagging while balancing trade-offs. So I suggest we plan to create a pre-release version v0.1.0-pre.1 for the initial version of github.com/go-gl/glfw/v3.4/glfw module after #400 is merged. Please let me know if you think that won't work well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

8 participants