go- suffix is not redundant? I mean it’s already in a vanity url with the
golang name in it.
Also AFAIK dashes are not supported in package names so the inner package is going to be named differently
We already have
github.com/docker/go-connections using the same “convention”.
In fact it has sub-packages like
github.com/docker/go-connections/nat are we going to do the same thing here?
Let me explain the thought process here.
The github repo name MUST have the name
go in it, and I believe should have also
sdk to make it clear that it’s only about the SDK and not a Go implementation of docker. A good counter example is
docker/cli which if you fork today to
username/cli has no information about what it actually is.
I asked Joffrey, the maintainer of
sdk, he said as long as it starts with
docker he doesn’t mind whether it’s
docker-py-sdk, hence my suggesting of
docker-sdk-go which is somewhat more idiomatic in the Go world, than
So far this is only for contributors to the SDK. Users would have a vanity URL at
golang.docker.io, and I thought
golang.docker.io/docker is the shortest and most straightforward URL. Again the majority of users won’t even see/care that it’s backed by github, so they wouldn’t see the mismatch between
If this mismatch is any weird, it is only to contributors, which although important, is not our primary concern with this project. Also, I asked around a bit, and what I got is:
- if possible avoid “last part of import path” being different from package name, so let’s avoid an import path ending with
/go-docker(or even worse
/docker-sdk-go) hosting a package named
/docker-sdk-gowith a package named
dockeris more confusing for users than the
/docker-sdk-gomismatch for contributors.
I will try to test this conclusion with more people outside docker.
Another important note: as a user, if you don’t know what package name to use when importing a URL, you can’t use
goimports to automatically detect it for you (as I previously thought), because you first have to use the package otherwise goimports removes the import line. Another point to prioritize the user over the contributor.
Hope this helps clarify.
My favorite option is:
- Frontend URL
- Backend URL
This option is my favorite because:
- docker-py doesn’t need to be changed, it’s already consistent. One less moving part to worry about.
- go-foo is a familiar standard for Go developers.
- The explanation is simple and memorable: “go-docker is the official Go SDK for Docker. Its latest version is 1.0.3”.
- docker.com and docker.io should be interchangeable aliases, with .io gradually falling out of favor for security and governance reasons.
- Internal consistency between frontend and backend URLs.
It’s a common pattern that will be familiar to many Go developers. I think it’s good for each SDK to adapt to its native platform as much as possible.
go-docker is a good proper noun. I can use it in sentences like “What version of go-docker are you using?”, or “go-docker 1.0 works with Docker CE 17.06”, and be clearly understood on the first try.
There are too many things with “docker” in their name, which creates ambiguity. It’s important to remove as much ambiguity as possible.
So, on the stable URI, I share some concerns with @fntlnz as
golang.docker.io/go-docker is quite redundant.
golang.docker.ioalready means it is only for Go and there is already
dockerin it. I would naively think that
golang.docker.io/dockeris the docker client,
golang.docker.io/docker/notaryis the notary client, etc…
- The use of
go-dockeris tricky. I do agrre with @shykes and @tiborvass on the fact that it makes it kinda makes it clearly understood. On the go side though, it is a little bit more tricky because this means the last part of the import fullname (i.e.
go-docker) is different from the identifier of the import used in the source (which will be
docker— and not
clientas it is now).
It’s the same for
gopkg.in/check.v1so it’s something that already exists in the Golang ecosystem. For clarity, people and tools tend to alias those imports (
import docker "golang.docker.io/go-docker") too. It is something relatively familiar to Go developers indeed.
My 2 cents: I would either go with
I agree that those sentences are well formed and really representative while talking but it’s still true that when a Go developer encounter a package with a different name than the FQDN she/he has to figure out about the inner package.
The problem is very notable when in your editor you expect the autocompletion to complete the package name when you write:
For example, with the actual
github.com/docker/docker/client I usually do these steps:
After that I save the file and it imports the
I suddenly note that
client is not a good name in my file because I might use another client and it’s not very representative so I change the import into:
In this case if the top level package is
go-client isn’t just a folder containing other packages like
github.com/docker/go-connections the normal workflow of most developers using that straightforward flow will be broken in the sense that you actually have to inspect the package in order to understand how it works.
A part from my doubts, I’m certainly sure that this can be mitigated by adding examples in the readme and by writing documentation.
I was told that
.io is not the most trustworthy TLD… But today I double-checked, and was told by our security team that the concern is not a dealbreaker.
So, from a developer experience perspective, my favorite URL is now
docker.io/go-docker What got me over the fence is the Upsin project, which is run by the core Go team, and uses
upspin.io/<package_name> as their import URL. If it’s good enough for Rob Pike, it’s good enough for me