go-gl / glfw

Go bindings for GLFW 3
BSD 3-Clause "New" or "Revised" License
1.56k stars 182 forks source link

Package name meta-issue, can we rename package to glfw? #123

Closed dmitshur closed 9 years ago

dmitshur commented 9 years ago

The example in the README has:

import (
    "fmt"
    glfw "github.com/go-gl/glfw3"
)

I always rename the glfw3 package to glfw so that it can be used like glfw.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 like glfw3.CreateWindow. It's a trivial difference, but still.

In an ideal world, I would like to see:

go-gl/glfw - latest version of glfw go-gl/gl/... - gl bindings (generated via glow)

go-gl/glow - only the glow binding generator itself

go-gl/glfw-legacy or go-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, just go 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?

dmitshur commented 9 years ago

Worth pointing out, there are two separate issues here:

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.

dmitshur commented 9 years ago

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.

dmitshur commented 9 years ago

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

slimsag commented 9 years ago

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

tapir commented 9 years ago

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.

dmitshur commented 9 years ago

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...

tapir commented 9 years ago

Why not use something like go-gl/glow:

Then we can use it like this.

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...

pwaller commented 9 years ago

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.

banthar commented 9 years ago

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

slimsag commented 9 years ago

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.

tapir commented 9 years ago

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.

slimsag commented 9 years ago

go get downloads the entire repository, yes. Only the packages you specify are built -- but the entire repository has to be downloaded still.

tapir commented 9 years ago

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.

dmitshur commented 9 years ago

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.

pwaller commented 9 years ago

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.

slimsag commented 9 years ago

I just checked the repo size with and without .git directories (at the devel_glfw3.1 branch):

This 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).

tapir commented 9 years ago

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.

tapir commented 9 years ago

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.

pwaller commented 9 years ago

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.

slimsag commented 9 years ago

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?

tapir commented 9 years ago

Shall we get this going?

dmitshur commented 9 years ago

What's the currently proposed naming plan?

slimsag commented 9 years ago

@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.

slimsag commented 9 years ago

Here is the rough draft, please take a look.

errcw commented 9 years ago

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.

slimsag commented 9 years ago

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.

errcw commented 9 years ago

I think there's value in avoiding surprise, which generally means providing some advance notice. Even a day is probably fine.

slimsag commented 9 years ago

Okay, sounds good.

slimsag commented 9 years ago

@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.

pwaller commented 9 years ago

@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 :)

dmitshur commented 9 years ago

(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.

  1. 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.

  2. 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.

tapir commented 9 years ago

Document is very good :+1:

dmitshur commented 9 years ago

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.

errcw commented 9 years ago

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.

slimsag commented 9 years ago

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.

slimsag commented 9 years ago

@go-gl/admin @go-gl/owners

Let's get this prepared for launch!

The plan to go forward

The big unveiling

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.

What's left?

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.

dmitshur commented 9 years ago

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.

dmitshur commented 9 years ago

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.

slimsag commented 9 years ago

@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.

dmitshur commented 9 years ago

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?

slimsag commented 9 years ago

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: image

dmitshur commented 9 years ago

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. :)

pwaller commented 9 years ago

@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.

dmitshur commented 9 years ago

@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.

dmitshur commented 9 years ago

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. :/

tapir commented 9 years ago

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.

tapir commented 9 years ago

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)

mbertschler commented 9 years ago

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).

slimsag commented 9 years ago

@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?

mbertschler commented 9 years ago

@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