Proposal: Rename package to githubv4.

[dmitshur]

This is something I've been thinking about for the last few months, and I am increasingly convinced this would be an improvement. If accepted, it's better to get this done sooner, before the library has many more users.

The proposal is:

-// Package githubql is a client library for accessing GitHub
+// Package githubv4 is a client library for accessing GitHub
 // GraphQL API v4 (https://developer.github.com/v4/).
 //
 // If you're looking for a client library for GitHub REST API v3,
 // the recommended package is github.com/google/go-github/github.
 //
 // Status: In active early research and development. The API will change when
 // opportunities for improvement are discovered; it is not yet frozen.
 //
 // For now, see README for more details.
-package githubql // import "github.com/shurcooL/githubql"
+package githubv4 // import "github.com/shurcooL/githubv4"

First, I think there are some issues with the current githubql name (at least in my mind). It sounds cool, like "GitHub Query Language", but that's not very accurate. If anything, it should've been githubgql for "GitHub GraphQL [API]".

It might be just me, but having githubql and graphql, I constantly keep mixing up their names, even though I'm well aware of their differences. I guess it's just that both start with "G" and end with "QL", which makes the names harder to differentiate.

Next, I think that githubv4 is a more practical name for the following reason. Currently, GitHub GraphQL API v4 is far from complete (and seemingly, it will not have feature parity with GitHub REST API v3 for many years). So during this transitional time, it's going to be very common to import both:

import (
    ...
    "github.com/google/go-github/github"
    "github.com/shurcooL/githubql"
)

github and githubql don't make for great package names in code that uses both. They're hard to tell apart, have different length names, etc.

So doing this seems favorable:

import (
    ...
    githubv3 "github.com/google/go-github/github"
    githubv4 "github.com/shurcooL/githubql"
)

Also, in theory, if GitHub were to release GitHub API v5, and it happened to also use GraphQL, that would be another data point showing that githubv4 is a better name than githubql.

Updating the code and moving/re-fetching the package is a bit annoying for users, but not too difficult or risky.

According to https://godoc.org/github.com/shurcooL/githubql?importers, there are not very many (public) importers at this time, so this seems viable.

I'm happy to hear thoughts or convincing arguments on this, if anyone has any. Thanks.

/cc @willnorris @gmlewis For your awareness and thoughts.

[willnorris]

👍 I also get a little confused when seeing graphql and githubql side-by-side.

[gmlewis]

I totally agree.

[dmitshur]

Thanks for feedback, I’m glad to hear the new name is well received.

I’ll make this change on May 8th (Tuesday).

[dmitshur]

I wrote the instructions for updating code in the commit message, but I'll copy it here:

This is a breaking API change. Updating code is easy. It can be done with an automated tool or by hand.

The gomvpkg tool (https://golang.org/x/tools/cmd/gomvpkg) can be used to rename your existing githubql package to githubv4, and update all code references in your GOPATH:

gomvpkg -from github.com/shurcooL/githubql -to github.com/shurcooL/githubv4

(You'll need to run it before you update to this commit.)

Otherwise, if you want to update your code manually, only the import declaration needs to be changed at first:

 import (
        // ...
-       "github.com/shurcooL/githubql"
+       githubql "github.com/shurcooL/githubv4"
 )

Afterwards, it's possible to update code to use the new githubv4 package name and remove the import rename.

Or, if you've already renamed the package to githubv4:

 import (
        // ...
        githubv3 "github.com/google/go-github/github"
-       githubv4 "github.com/shurcooL/githubql"
+       "github.com/shurcooL/githubv4"
 )