Consider adding release tags #188
Comments
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? |
|
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. |
|
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 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. |
|
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. |
|
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):
(Paraphrasing)
The obvious problem with tags is that the authors of So here are some proposals, in no particular order. A) Do nothing. Users grab a git sha and run with that.
B) Take the same tag as glfw.
C) Use a different tagging scheme than glfw
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
If you have an opinion please comment and point towards your favourite :) |
|
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 |
I don't think it will be confusing for users if we use multi-module-repositories. require (
github.com/go-gl/glfw/v3.3/glfw v0.0.0-20191124195120-e5ec43523f6f
)We have the version of glfw used ( the go.mod will look something like: When knowing the root directory structure ( The I don't think we need to go down as having the Overall I'd say option
Is already taking care by the version in the path and the |
|
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 :) |
|
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 |
Sounds good to me. Any objections from anyone? |
|
I'm fine, but when do we make |
|
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.
This part isn't true. All major versions other than v0 and v1 require a |
|
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. |
|
Oh, would it still be possible to add some breaking change to go-gl/glfw? Then v0.x would make sense. |
|
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. |
|
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. |
|
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 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. |
I am not a fan of having the version as Also, I would be in favour of doing a
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. |
|
@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 |
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.
The text was updated successfully, but these errors were encountered: