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

[dmitshur]

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]

Document LGTM.

[slimsag]

Doc updated with a release date of this Saturday.

@pwaller @banthar @errcw PTAL so we can announce the doc.

[errcw]

LGTM

[pwaller]

LGTM

[tapir]

If we're going for a Sunday release, I think we should release the doc today or tomorrow max.

[slimsag]

If we're going for a Sunday release, I think we should release the doc today or tomorrow max.

Agreed. Let's release today. I'll give it a few more hours in case anyone opposes, after that I'll submit to reddit and HN if nobody else does.

[ghost]

+1

I would make it abundantly clear that this is an announcement of how it's going to be; not a request for comments. So unless someone spots a show-stopping problem (exceedingly unlikely), this is what's going to happen.

[slimsag]

I would make it abundantly clear that this is an announcement of how it's going to be; not a request for comments.

I'm opposed to making further changes at this point. The doc already clearly states at the front:

This document (released early) describes the changes that are to be enacted on 2015-02-22.

I'll be posting the doc to various Go discussion area's now.

[slimsag]

Sent:

• Reddit
• Hacker News
• golang-nuts Mailing List
• go-gl Mailing List
• Also sent to gophers.slack.com's showandtell channel.

[dmitshur]

Thanks Stephen! I've (edited your post to) make the HN link non-clickable, because I think they'll flag it as a voting ring otherwise. If you want to upvote it, go to HN directly and find it there (under "new").

[pwaller]

From @rogpeppe on go-nuts:

Might I suggest that the version numbers in the new import paths start with a leading "v"? For example github.com/go-gl/glfw/v3.0/glfw .

That way they're compatible with the govers import path rewriting tool [1], so future version upgrades can be as simple as running:

govers github.com/go-gl/glfw/v4.0/glfw 

Without the leading "v", it's difficult for a tool to automatically recognise the version number in the path, and it's a convention that other places (for example gopkg.in and google API packages) already honour.

I'd also suggest that only the major version number be included, allowing backwardly compatible changes without import path rewriting. (I'm assuming here that some form of semantic versioning is used).

cheers, rog.

[1] github.com/rogpeppe/govers

[tapir]

very good point

[dmitshur]

Comment on Reddit:

This document does not go into any refactor of the examples repository. Will that be moved as well? I found it annoying trying to wade through inevitable build errors in that repo while trying to learn.

Great point. I think having outdated examples that don't compile is even worse than having no examples at all. We should really limit their number to a more manageable one and keep them updated. But this can be done separately afterwards.

[pwaller]

:+1: to the examples. It would be great if we could try and enforce that they all at least build and preferably run.

[dmitshur]

Yep, with Travis.

[dmitshur]

Fixed a typo in the import paths (thanks to a redditor for pointing it out).

The correct spelling is compatibility, not compatability. Source is dictionary and https://www.opengl.org/wiki/Core_And_Compatibility_in_Contexts.

[slimsag]

Apologies for the incorrect compatibility spelling. That would've been bad.

I am also in favor of putting v prefixes onto version numbersa s @rogpeppe suggested. If we do it to GLFW, we should do it to the GL bindings too, though.

[dmitshur]

I wanted to clarify @rogpeppe's suggestion, so I asked him and got this reply:

Hi rog. For my information, if we were to add the v prefix to have github.com/go-gl/glfw/v3.1/glfw and github.com/go-gl/glfw/v3.2/glfw in the future, would that be enough?

Or does it need to be major version only, hence something like github.com/go-gl/glfw/v31/glfw?

Or is .0 mandatory, meaning github.com/go-gl/glfw/v31.0/glfw is what you're suggesting?

Note that we are using minor version of upstream GLFW C library as an effective "major" version of the GLFW Go package, i.e. it may introduce breaking API changes, that's why I went to v31 in examples above instead of just dropping the minor version.

Thank you, Dmitri

Yes that would be enough (try it to make sure if you like) as the regexp it uses includes a dot. If the upstream C package introduces API-breaking changes on minor versions then I can entirely understand why you might want to put the minor version in the import paths.

cheers, rog.

So if I understood that correctly, we just need to add the v prefix in front of 3.0 or 3.1, no other changes are needed.

I am in favor of doing that, definitely for GLFW.

[dmitshur]

We've added the v prefix as suggested by @rogpeppe to the plan in front of all versions in the new import paths.

[dmitshur]

Starting preparation work. Keeping track of it here (will edit as I make progress):

GLFW

1. Made https://github.com/go-gl/glfw/pull/49 PR, needs reviewing. After glfw repo is moved into go-gl-legacy org, this PR can be merged.
2. Made https://github.com/go-gl/glfw3/pull/126 PR, needs more thorough reviewing. After glfw repo is moved out of the way, glfw3 repo can be renamed to glfw, and this PR can be merged.
3. Created https://github.com/go-gl/glfw3-clone-to-be-renamed repo and https://github.com/go-gl/glfw3-clone-to-be-renamed/pull/1 PR, needs reviewing. After glfw3 repo is moved out of the way, glfw3-clone-to-be-renamed repo should be moved into its place.

GLFW preparations are complete.

GL

1. Created https://github.com/go-gl/gl-new-to-be-renamed repo, this is where glow generated OpenGL bindings will be moved. After gl repo is moved to go-gl-legacy organization, it should be renamed to gl.
   • Pushed its contents that preserve bindings history, rewrite internal import paths, add modified README. See https://github.com/go-gl/gl-new-to-be-renamed/commits/early-2015-overhaul.
   • Created issue https://github.com/go-gl/gl-new-to-be-renamed/issues/1 (not a PR since this is a new repo), needs review.

(GL preparations are not yet complete, some more work remains, but it'll be done today.)

[dmitshur]

Okay, all the GLFW preparations are ready, all 3 PRs have been reviewed. I'm going to execute the plan for GLFW now. (Then we'll get to work on finishing and executing GL.)

[slimsag]

For any interested parties -- we're in gophers.slack.com (#go-gl channel) discussing and @shurcooL is narrating the whole plan / what is going on as we go.

[dmitshur]

The GLFW part of the plan is now live. Everything appears okay and things work.

Reopening this to continue work on the GL part of the plan.

[dmitshur]

GL preparations are complete. See https://github.com/go-gl/gl-new-to-be-renamed/issues/1.

[dmitshur]

Okay, all the GL preparations are ready, the single issue has been reviewed. I'm going to execute the plan for GL now, completing the user-facing aspect of the early 2015 overhaul plan.

We will still have some background improvement work remaining afterwards (updating glow repo to generate new glow bindings in the right place, without manual updating required, making a PR to remove GL bindings from glow repo in 30 days, etc.), but it's not mandatory for that to be done today.

[dmitshur]

The GL part of the plan is now live. Everything appears okay and things seem to work as expected.

That completes the early 2015 go-gl massive overhaul plan (aside from minor follow up things we will keep working on)! Congratulations and huge thanks to everyone!

[dmitshur]

I just want to say, when I created this issue, I honestly did not expect us to take action and make such improvements. In my original post, I wrote:

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 guess we live in a more ideal world now. :D

I know there will be some (really small) annoyances to update import paths in the short term, but I'm sure in a few months it'll be really nice to look back and be happy we made this jump. Again, thanks!

[slimsag]

Thank you everyone for all of your input and help improving the plan -- and a big thanks to @shurcooL for following through with it (he did all of the work to enact the plan).

Cheers to all! :smiley:

[tapir]

Thanks everybody :beers:

[pwaller]

Great job guys. :beers: