Topic: Find a good and non-confusing home for the remaining monolith

Architecture
81

Prepending the 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

82

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?

83

Let me explain the thought process here.

The github repo name MUST have the name docker, and 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 docker-py about sdk, he said as long as it starts with docker he doesn’t mind whether it’s docker-sdk-py or docker-py-sdk, hence my suggesting of docker-sdk-go which is somewhat more idiomatic in the Go world, than docker-go-sdk.

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 /docker and /docker-sdk-go.

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. Hence /docker.
  • /docker-sdk-go with a package named docker is more confusing for users than the /docker vs /docker-sdk-go mismatch 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.

84

My favorite option is:

  • Frontend URL golang.docker.com/go-docker
  • Backend URL github.com/docker/go-docker

This option is my favorite because:

  1. docker-py doesn’t need to be changed, it’s already consistent. One less moving part to worry about.
  2. go-foo is a familiar standard for Go developers.
  3. The explanation is simple and memorable: “go-docker is the official Go SDK for Docker. Its latest version is 1.0.3”.
  4. docker.com and docker.io should be interchangeable aliases, with .io gradually falling out of favor for security and governance reasons.
  5. Internal consistency between frontend and backend URLs.
85

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.

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

86

So, on the stable URI, I share some concerns with @fntlnz as golang.docker.io/go-docker is quite redundant.

  • golang.docker.io already means it is only for Go and there is already docker in it. I would naively think that golang.docker.io/docker is the docker client, golang.docker.io/docker/notary is the notary client, etc…
  • The use of go-docker is 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. golang.docker.io/go-docker) is different from the identifier of the import used in the source (which will be docker — and not client as it is now).
    It’s the same for gopkg.in package like gopkg.in/check.v1 so 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 golang.docker.io/docker or dev.docker.io/go-docker :angel:.

87

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:

I write

client.DefaultDockerHost()

After that I save the file and it imports the github.com/docker/docker/client package.

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:

docker "github.com/docker/docker/client"

In this case if the top level package is go-client and 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.

88

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

89

Hi folks,

I opened a Github issue (easier to keep up-to-date) with an alternative proposal to complete the Moby transition: https://github.com/moby/moby/issues/35115

Feel free to check it out. At this point, this email thread became too big anyway.

Thanks!