Closed dmitshur closed 9 years ago
Worth pointing out, there are two separate issues here:
glfw3
, but readme suggests renaming it to glfw
when importing)github.com/go-gl/glfw3
)I'd like to see both change to glfw
, but changing just the package name while keeping same import path is still an improvement IMO.
I'm raising this question now because of the breaking API changes for GLFW 3.1 update, I feel like it's a chance to make a change here as well.
For reference,
Users of glfw3
(currently 3.0.4, soon to be 3.1) package - https://godoc.org/github.com/go-gl/glfw3?importers
Users of glfw
(GLFW 2.7) package - https://godoc.org/github.com/go-gl/glfw3?importers
FWIW I've now responded to two separate people on /r/golang regarding the difficulties of using go-gl/gl
due to the fact that it depends on GLEW. Each one was suprised to find out that go-gl/gl
is not generated by go-gl/glow
Although glfw
would be ideal I think we're stuck with glfw3
. Changing the repo names would be too bothersome. We don't really know how many people are using go-gl/glfw
.
But, If removing go-gl/glfw
was not a problem then we could have 2 repos in sync (glfw
and glfw3
) and have glfw3
one print out a message saying something like "Use go-gl/glfw
instead"
EDIT: But then again we would have to do the same thing all over again every major GLFW version.
EDIT: But then again we would have to do the same thing all over again every major GLFW version.
I don't think so. We can use same package for all future GLFW versions. If there are breaking API changes, we can adopt gopkg.in-style imports, or just not maintain backwards compatibility. We're not creating a new repo for 3.1, despite some breaking changes (well, they're mostly on our side, not GLFW). Although I suppose it would depend on how significantly the GLFW 4.0 api changes are. Hmm...
Why not use something like go-gl/glow
:
go get github.com/go-gl/glow/gl-core/3.2/gl
go get github.com/go-gl/glow/gl-core/3.3/gl
Then we can use it like this.
go get github.com/go-gl/glfw/2.7/glfw
go get github.com/go-gl/glfw/3.0/glfw
go get github.com/go-gl/glfw/3.1/glfw
It doesn't matter if mainstream 3.2 breaks compatibility or not, we can just create a new sub-package and keep going.
Of course there is still the disadvantage that all the current GLFW users will have to change their import line...
I have consulted @jteeuwen and he does not mind relinquishing the glfw name. He was in favour of removing the old bindings entirely to keep things simple. I'm in favour of keeping them around but maybe with an unappetising name like "-legacy".
I think we should ask @banthar as a matter of courtesy if he minds if we give up the go-gl/gl
namespace and if so, we should move glow there.
However, it would be nice if we could arrange something so that we don't have to cause breakage next time around. Either by having vanity URLs of some sort, or @tapir's suggestion above.
I think we should ask @banthar as a matter of courtesy if he minds if we give up the go-gl/gl namespace and if so, we should move glow there.
Whatever you decide is fine with me.
However, it would be nice if we could arrange something so that we don't have to cause breakage next time around. Either by having vanity URLs of some sort, or @tapir's suggestion above.
I think this is the most important thing. If you you are going to break the API, at least make sure you don't have to do it ever again. I would go with @tapir's suggestion, single repository per major version or with this: http://labix.org/gopkg.in
Please don't place multiple packages in the same repo -- we'll end up with unnecessarily large repositories forcing everyone to download all previous versions when probably only the most recent matters to them.
Are you sure? AFAIK with glow method you don't download the whole repo. On 26 Jan 2015 21:59, "Stephen Gutekanst" notifications@github.com wrote:
Please don't place multiple packages in the same repo -- we'll end up with unnecessarily large repositories forcing everyone to download all previous versions when probably only the most recent matters to them.
— Reply to this email directly or view it on GitHub https://github.com/go-gl/glfw3/issues/123#issuecomment-71526985.
go get
downloads the entire repository, yes. Only the packages you specify are built -- but the entire repository has to be downloaded still.
I believe that's not really a big problem. you download it only once. building is the important part.
EDIT
On 26 Jan 2015 22:03, "Stephen Gutekanst" notifications@github.com wrote:
go get downloads the entire repository, yes. Only the packages you specify are built -- but the entire repository has to be downloaded still.
— Reply to this email directly or view it on GitHub https://github.com/go-gl/glfw3/issues/123#issuecomment-71527576.
https://twitter.com/elmindreda/status/560101893507399681
I'll make a PR for that particular issue, but IMO it demonstrates a larger problem. Edit: Opened https://github.com/go-gl/gl/pull/179.
I'm 'fairly' keen to keep repositories small. I surprisingly frequently find myself on a bad connection having to download the whole thing. And newbies might find themselves in that position, and if they have to download tens-hundreds of megabytes whilst travelling to a game-making hackathon they might just pass up the opportunity to try go if they can't clone the repository easily.
I just checked the repo size with and without .git
directories (at the devel_glfw3.1
branch):
.git
(i.e. no-history): 1.9MB.git
(i.e. with history): 1.9MBThis would stand to reason that the entire package (and it's C sources) could be completely rewritten 13 times over and stay at around 25MB.
Lets just make sure we don't ever commit any binaries (texture images for examples.. etc) into the repo (which is bad practice anyway).
I retract my previous statement, and am in favor of taking @tapir's approach (or gopkg.in
, either way works).
Probably after 3-4 versions we can safely start deleting deprecated ones. If it ever comes to that.
I propose, whatever method we choose, we keep it standard among go-gl projects.
I'm more inclined to the glow way of versioning because I don't like the idea to depend on a third party like gopkg.in.
Bear in mind that once something is in the git history it can't easily be deleted in a way that recovers the storage cost in github. However, it doesn't currently sound too bad if the size is only ~2MB so far.
Probably after 3-4 versions we can safely start deleting deprecated ones. If it ever comes to that.
As @pwaller mentions we can't recover the storage penalty for this, as it all stays in the git history (unless we want to blow away the whole git repo's history -- not nice!). But it's only 2MB thus far, I think we'll be okay long-term as long as we only commit source code, not any binaries, images, etc.
I'm more inclined to the glow way of versioning because I don't like the idea to depend on a third party like gopkg.in.
I'm fine with that. But ideally we will choose something that will work with shurcooL's Go-Package-Store
tool in the future, so users can launch that up and see that a new version of the GLFW bindings are available and upgrade to it easily.
@shurcooL do you have any idea's on what a good directory structure that G-P-S could identify well with?
Shall we get this going?
What's the currently proposed naming plan?
@tapir @shurcooL @pwaller @banthar since we're looking at breaking API compatibility for a lot of users, I figure it'd be good if we have something we can link to / announce on mailing lists, reddit, etc, to get everyone up-to-date on what is going on.
I'll be doing a small write-up of the changes, what it all means, etc as a public Google Doc. We can all link to it / announce the plans on various sites when they take place then.
Let's not act on anything until we all get LGTM's on it so everyone is good. I'll link to it here in the next few hours.
Here is the rough draft, please take a look.
I'm generally on board with the plan though I'm decidedly shy about breaking existing code--we should be sure to announce this change broadly before enacting it.
The doc looks fine. I very quickly copy edited it though it needs another pass or two.
I'm generally on board with the plan though I'm decidedly shy about breaking existing code--we should be sure to announce this change broadly before enacting it.
Is it very important to announce it before enacting it? I don't think it is so long as we announce it largely (go-nuts
ML, go-gl
ML, /r/golang
etc).
Thanks for the review, it was a really quick draft -- I'll resolve those right now.
I think there's value in avoiding surprise, which generally means providing some advance notice. Even a day is probably fine.
Okay, sounds good.
@errcw I added a section to the doc to relay that to the reader:
This document (released one day early) describes the changes that are to come on (INSERT DATE HERE).
I'll insert the real date once I hear back from others.
@slimsag everything I've read LGTM, good work!
It's probably also worth considering updating http://go-gl.github.io/ (over at https://github.com/go-gl/go-gl.github.com) if anyone is up for that. I apologise for my inactivity in recent times, I'm fairly inundated with other things at the moment and it is great to see you all moving things forward in a professional manner :)
(I moved this comment from the google doc.)
Overall, this document is stellar and looks good to me. If it's enacted as described now, I'm happy with that.
A few quick thoughts (I want to provide more elaborate feedback later, if I can find time). These are just optional thoughts that can be ignored if we can't find a better way.
Think about GitHub issues and where they'll end up. Currently, I see that github.com/go-gl/gl-compatibility, github.com/go-gl/gl-core, and github.com/go-gl/gl will be 3 separate issue trackers.
Similarly, I see that GLFW 2 and GLFW 3 will share issue tracking.
Is that acceptable? Or can we do better without sacrificing import paths? I think good import paths are much more important. Just something to consider.
GLFW 3 (the C library) api was compatible between 3.0 and 3.1. the Go library is not because of our API overhaul/dev changes.
So consider the future. 3.2 (C library) comes out. I think glfw/3.1/ (Go package) can be upgraded to latest 3.x version without breaking API changes.
So is that okay? We might have Go import path 3.1 but C library 3.2 or 3.3.
And when we do want to break Go API, would it be glfw/3.2 or glfw/3.{whatever current C library minor version is}.
Again, just optional question/thoughts that came to me when looking this over.
I do think it looks really really good and a huge improvement over previous situation, and also updating legacy/new code should be quite smooth.
Document is very good :+1:
While I'm happy with the currently proposed new import paths since I think it's a huge improvement over current version, I have a suggestion for slightly modified proposed new import paths. The bold part is the repo name.
Old Path | Proposed Path 1 | Proposed Path 2 |
---|---|---|
github.com/go-gl/gl | github.com/go-gl/gl-legacy | github.com/go-gl/gl-legacy |
github.com/go-gl/glow/gl-compatibility/{version}/gl | github.com/go-gl/gl-compatibility/{version}/gl | github.com/go-gl/gl/compatibility/{version}/gl |
github.com/go-gl/glow/gl-core/{version}/gl | github.com/go-gl/gl-core/{version}/gl | github.com/go-gl/gl/core/{version}/gl |
github.com/go-gl/glow/gl/2.1/gl | github.com/go-gl/gl/2.1/gl | github.com/go-gl/gl/legacy/2.1/gl |
What do you think of the Proposed Path 2 column?
There are a few advantages IMO. First, all glow-generated bindings are under the same repo, with a more similar path pattern. That means they share same issue tracker, and it's easier to push changes to all glow-generated bindings at once. I don't see the advantage of splitting core/compatibility/legacy bindings into separate repos, are there any?
For the GLFW bindings, I am still thinking through an alternative scheme where the 2.x bindings are in a separate repo. Perhaps this:
Old Path | Proposed Path 1 | Proposed Path 2 |
---|---|---|
github.com/go-gl/glfw @ master | github.com/go-gl/glfw/2.0/glfw | github.com/go-gl/glfw-legacy/2.0/glfw |
github.com/go-gl/glfw3 @ master | github.com/go-gl/glfw/3.0/glfw | github.com/go-gl/glfw/3.0/glfw |
github.com/go-gl/glfw3 @ devel_glfw3.1 | github.com/go-gl/glfw/3.1/glfw | github.com/go-gl/glfw/3.1/glfw |
The motivation is to keep GLFW 2.x separate from 3.x, since they're completely distinct and very few people would be interested in having both. Consider that the C library does that too: github.com/glfw/glfw has 3.x and github.com/glfw/glfw-legacy has 2.x.
What do you think of the Proposed Path 2 column?
I strongly agree we should keep Glow and the generated bindings in a single repository. I missed this aspect in the original proposal.
The motivation is to keep GLFW 2.x separate from 3.x
To play devil's advocate, we keep the legacy (2.x) GL bindings in the same repository as the modern (3.x/4.x) bindings so keeping a single GLFW repository would be the most consistent structure.
Sorry for the path issues. I actually DID NOT intend for the gl
paths to be that way: I've updated the doc exactly as @shurcooL said: please take a look.
The motivation is to keep GLFW 2.x separate from 3.x, since they're completely distinct and very few people would be interested in having both. Consider that the C library does that too: github.com/glfw/glfw has 3.x and github.com/glfw/glfw-legacy has 2.x.
I know me, you, and probably most others won't be using the 2.x bindings. But I think from a consistency standpoint it makes the most sense to have them all in the same repository. What would we do when GLFW 3 is 'legacy' ? github.com/go-gl/glfw-legacy-3
? Then we're back where we started IMHO.
For issues, we can use labels to set versions apart.
Highly agree.
For consistency's sake I would prefer a new import path for every GLFW C version. Otherwise it's misleading to import 3.1 and end up with 3.2.
Highly agree. Also, GLFW versions only come out every year or so -- and we'll be exposing new errors returned by functions at each minor release probably anyway. Separate paths for minor versions make the most sense.
I strongly agree we should keep Glow and the generated bindings in a single repository. I missed this aspect in the original proposal.
I agree. Lets put all the Glow code and it's generated bindings in the gl
repository.
@go-gl/admin @go-gl/owners
go-gl/glfw
to move glfw3
and glfw3@devel_glfw3.1
.go-gl/gl
to move glow
.
gl-
prefix).After the two PR's are ready, and if it still looks good to everyone, we will finalize the proposal document with a date and publish it online. After 24-48hrs, we can move the issues over and merge the pull requests.
If you have concerns, questions, comments, etc: Now is the time to raise them!
@pwaller I haven't heard from you regarding the doc -- are you still okay with whatever we collectively decide to do? Just want to make sure we don't miss anyone's opinions on this change.
Sorry for the path issues. I actually DID NOT intend for the
gl
paths to be that way: I've updated the doc exactly as @shurcooL said: please take a look.
Let me review those changes now. I have some more feedback regarding other points also.
we can move the issues over
Is there a way to seamlessly move issues between GitHub repos? Or did you mean by manually creating new issues/copying & pasting text/closing old ones.
The closest thing to seamlessly moving issues I'm aware of is renaming the repository itself.
@shurcooL Sounds good. Again, we won't do anything if anyone has feedback/concerns. I don't want to cut anyone short.
Is there a way to seamlessly move issues between GitHub repos? Or did you mean by manually creating new issues/copying & pasting text/closing old ones.
Sorry, I meant to link to the github issue mover project. But only a @go-gl/admin has the rights to enable it for use, I think (at least, I don't have access to).
I don't think it can preserve the owner (i.e. it just copies the text and closes the old ones for you), though.
If we rename the repo, though, the forks are associated with the old repo and those owner's won't get notifications about their fork being out-of-date.
If we rename the repo, though, the forks are associated with the old repo and those owner's won't get notifications about their fork being out-of-date.
Can you elaborate please? Suppose someone has a fork of go-gl/glfw
, which we can rename to go-gl/glfw-legacy
. Their fork would now be a fork of go-gl/glfw-legacy
, which is correct. Similarly, anyone who has a fork of go-gl/glfw3
will see their fork become a fork of the new go-gl/glfw
, which is also correct. Am I overlooking something?
For example, I have a fork of gopheracedemy's web-site. If they moved that to a -legacy
repository -- I might not spot it and, because they won't be changing that repository ever again, I might think my fork is completely up-to-date.
Whereas if they made the changes through commits of some means, I could git pull
or go get -u
locally -- or even see a warning on my fork on the GitHub website:
I have many points I want to address in further detail... so this'll be a long comment.
What do you think of the Proposed Path 2 column?
I strongly agree we should keep Glow and the generated bindings in a single repository. I missed this aspect in the original proposal.
I strongly agree the generated bindings (2.1, core, compatibility) should be in the same repo. I feel less strongly about glow the generator command and the generated bindings, but I do think it's better for them to be in separate repos.
I see glow as being similar to stringer
(http://godoc.org/golang.org/x/tools/cmd/stringer). stringer
is a code generator that a certain project may use, but stringer
is not a part of that repo, it's a stand-alone tool. Similarly, I see glow
as something used to generate the future go-gl/gl
bindings, but I don't see a good reason why the generator itself should be a part of that repo. Users interested in bindings only will not want it.
Your comment was quite brief so I might've misunderstood you, but if you disagree about keeping glow
at go-gl/glow
and moving generated bindings to go-gl/gl
, can you please explain why you think it's better?
The motivation is to keep GLFW 2.x separate from 3.x
To play devil's advocate, we keep the legacy (2.x) GL bindings in the same repository as the modern (3.x/4.x) bindings so keeping a single GLFW repository would be the most consistent structure.
Okay, before I reply to this, let me clear up the terminology. Perhaps I shouldn't have used "legacy" for the 2.1 path, because IMO it's misleading. Let me use a longer but more descriptive term instead to better explain what I had in mind:
Old Path | Proposed Path 2 (alt.) |
---|---|
github.com/go-gl/gl | github.com/go-gl/gl-legacy |
github.com/go-gl/glow/gl-compatibility/{version}/gl | github.com/go-gl/gl/compatibility/{version}/gl |
github.com/go-gl/glow/gl-core/{version}/gl | github.com/go-gl/gl/core/{version}/gl |
github.com/go-gl/glow/gl/2.1/gl | github.com/go-gl/gl/neither-core-nor-compatibility/2.1/gl |
In the alternative Proposed Path 2 column, I used neither-core-nor-compatibility
instead of legacy
for OpenGL 2.1 bindings.
The reason I introduced legacy
in there is because I wanted to keep import path more consistent between all versions of OpenGL. I don't think OpenGL 2.1 should have a shorter import path than OpenGL 4.5. But it's neither core nor compatibility, so I used legacy. Despite that name, OpenGL 2.1 bindings are not legacy in the other, more common meaning of the word, because modern, currently maintained apps may choose to use 2.1. 2.1 is still useful with extensions, and is supported by more platforms than 4.5 (since 4.5 is "too new").
The true meaning of legacy, IMO, is packages that no well maintained, current app should be using. Instead, only unmaintained, older apps may use it, and the idea is to preserve those packages so the unmaintained code can (after updating import path) continue to work.
So, with that perspective, I see GLFW 2.x as legacy. No modern/maintained app should be using it, because GLFW 3.x completely supersedes it. Similarly for current non-glow generated bindings.
When GLFW 4.x and 5.x come out, I see the current 3.x moving into the -legacy
subrepo:
go-gl/glfw/3.1
-> go-gl/glfw-legacy/3.1
go-gl/glfw/4.0
added.
I think it's a good idea to be able to move the less-used packages into a separate repo so they don't get in the way of modern/maintained packages. It's just a question of how soon to do it, but it should be done eventually (e.g., by the time GLFW 6.0 comes out, there's no reason for GLFW 3.1 to not be moved into glfw-legacy along with GLFW 2.x).
The motivation is to keep GLFW 2.x separate from 3.x, since they're completely distinct and very few people would be interested in having both. Consider that the C library does that too: github.com/glfw/glfw has 3.x and github.com/glfw/glfw-legacy has 2.x.
I know me, you, and probably most others won't be using the 2.x bindings. But I think from a consistency standpoint it makes the most sense to have them all in the same repository. What would we do when GLFW 3 is 'legacy' ?
github.com/go-gl/glfw-legacy-3
? Then we're back where we started IMHO.
This is mostly addressed by my answer above.
This is the pattern I'm currently picturing:
github.com/go-gl/glfw-legacy/{version}/glfw
- deprecated (currently 2.x).
github.com/go-gl/glfw/{version}/glfw
- modern (currently 3.0 and 3.1).
Also, GLFW versions only come out every year or so -- and we'll be exposing new errors returned by functions at each minor release probably anyway. Separate paths for minor versions make the most sense.
Ok, I think that should be fine. It does enforce a certain schedule on our versions which may not correspond to the perfect versioning scheme, but I think it's the best choice out of all alternatives. :+1:
For example, I have a fork of gopheracedemy's web-site. If they moved that to a
-legacy
repository -- I might not spot it and, because they won't be changing that repository ever again, I might think my fork is completely up-to-date.
If someone has a fork of glfw
the 2.x bindings with some changes, I don't think their changes will be at at all compatible with glfw3.1. So I don't see how it makes sense to basically swap out the original repo they've forked (i.e., GLFW 2.7 bindings) with something completely incompatible.
For all other points that I did not reply to, I agree with them completely, and that's why I left them out. :)
@slimsag I was among the first to respond to the document in this issue, yes, I approve. :)
I'm pleased that you guys are moving forward on this without much input from me. I'm happy for you to move forward in my absence if you have a quorum. Ideally the package owners should be aware of and happy with what's happening (which I think everyone is as far as I know). You should feel free to go ahead.
@slimsag and I have worked through a lot of different possibilities and their cons/pros today, which resulted in some tweaks to our proposed plan. It is nearing a point where we both can say "LGTM" and ask everyone else to give their LGTM, but it may be a few more days.
It has been a week. I still think our current draft proposed import path plan for the OpenGL bindings repos is excellent and does not need any changes. However, I do not have any additional clarity regarding the GLFW 2 and GLFW 3 (and 3.1) import paths. :/
An extra repo for legacy versions is OK for me. In fact I would be OK if we were to completely eliminate GLFW 2.7 and OpenGL 2.1. They should not be used. But I understand that there are still people using it so, let's keep them under legacy. This way we're promoting the use of better libraries.
It's been 1 month since the official release of 3.1. I think it's now time to get things going.
I'm for @shurcooL's proposition of separating the legacy and modern versions. On the other hand I still think we should have a new import path for every C version of GLFW: Updating 3.1 to 3.2 and still using 3.1 import path is no go for me.
So @shurcooL @slimsag @pwaller @banthar @errcw Does anybody have anything extra to add? If not maybe we should already release the doc that @slimsag created (with the recent updates ofcourse)
I also don't think that new glfw versions should use the same import path. I think @shurcooL's last proposition for the glfw import paths is good because they are consistent with the glow imports.
This is the pattern I'm currently picturing:
github.com/go-gl/glfw-legacy/{version}/glfw
- deprecated (currently 2.x).github.com/go-gl/glfw/{version}/glfw
- modern (currently 3.0 and 3.1).
@mbertschler If possible, please only comment on / review the linked doc. It's easier to see the single plan rather than dig through the comments here to understand what's going on.
@go-gl/admin @go-gl/owners With no further modifications -- the doc LGTM. @shurcooL Do we have your LGTM on the doc at this point?
@slimsag sorry I already was in the doc before but didn't see that there was more to it than the first paragraph :/ document LGTM
The example in the README has:
I always rename the
glfw3
package toglfw
so that it can be used likeglfw.CreateWindow
. I think the majority of people do the same, but I wouldn't be surprised if I find some people forgetting to do that and having incompatible code likeglfw3.CreateWindow
. It's a trivial difference, but still.In an ideal world, I would like to see:
go-gl/glfw
- latest version of glfwgo-gl/gl/...
- gl bindings (generated via glow)go-gl/glow
- only the glow binding generator itselfgo-gl/glfw-legacy
orgo-gl-legacy/glfw
- glfw 2.7 bindings.That would be best for current users and new users who are just getting familiar with what is available under go-gl.
I don't think it's the best outcome to have legacy, outdated glfw 2.7 bindings using up the
github.com/go-gl/glfw
import path. Especially since this is Go, I see very little reason anyone would have to use older GLFW versions unless they have some legacy code they want to maintain; in all other cases you're better off with the latest stable GLFW version. This is not C++ where it's hard to update, justgo get -u
.Of course, changing import paths is not easy, it has costs, and may not be possible. But I just wanted us to consider, can we do anything to improve the situation? What other people's thoughts?