RFC: archiving v1.12.0 tag as "old-v1.12.0" to prepare for becoming a go module

[thaJeztah]

The v1.12.0 tag was created pre go modules, and was never intended to be a "release".

Before go modules, tags were "opt-in", and could "optionally" be used as a
reference for a version to use, but when go modules were introduced, tags
got "meaning", and in this case "latest" is no longer "latest", but using
the last "released" version (v1.12.0 in this case).

While there are no plans to start tagging releases of this project, we do have
the intent to move this repository, and to make it a module (adding a go.mod).

To prevent users from getting an old version of this code, and to run into
problems where the old version uses the incorrect import path, this tag is
created from the v1.12.0 tag (commit 9d4c2f7),
with the intent to delete that tag.

git rev-list -n 1 old-v1.12.0
9d4c2f73124e70f8fa85f9076635b827d17b109f

git rev-list -n 1 v1.12.0
9d4c2f73124e70f8fa85f9076635b827d17b109f

The old-v1.12.0 tag was created: https://github.com/docker/swarmkit/releases/tag/old-v1.12.0

to discuss

As the v1.12.0 tag existed, go modules used it as reference to generate pseudo
versions, see https://grep.app/search?q=github.com/docker/swarmkit%20v1.12.

This means that some projects have pseudo-versions in their go.mod like the
ones below:

github.com/docker/swarmkit v1.12.1-0.20220307221335-616e8db4c3b0

github.com/docker/swarmkit v1.12.1-0.20180726190244-7567d47988d8 // indirect

I suspect those references become invalid once The GOPROXY module cache expires,
which could be potentially disruptive.

That said, the scope (if grep.app is to be trusted) looks to be limited to
only a couple of repositories;

• https://github.com/docker/cli (see vendor.mod)
• https://github.com/moby/moby (see vendor.mod)
• https://github.com/GoogleContainerTools/kaniko (see go.mod)

First two from that list we can deal with, for kaniko, it's an // indirect, which likely means the problem should go away if they upgrade to a more current version of Docker (see go.mod)

[corhere]

Go's documentation advises against deleting tags.

Once a tag is created, it should not be deleted or changed to a different revision. Versions are authenticated to ensure safe, repeatable builds. If a tag is modified, clients may see a security error when downloading it. Even after a tag is deleted, its content may remain available on module proxies.

The scope of disruption extends beyond the three public projects. There are non-public projects including Mirantis Container Runtime which would be impacted as well. Upgrading the problem away is not always an option, especially on long-term maintenance branches.

There's a built-in solution to retracting unintended releases of Go modules: the retract directive. When you add the go.mod file to the repo, add

retract (
        v1.12.0 // Not intended as a Swarmkit release.
        v1.12.1 // Contains retractions only.
)

to it and tag it as v1.12.1. The go tooling will not consider either tag as @latest.

---

Alternative: make a clean break

Go identifies a module by its module path, so giving the module a different identity will signal to the Go module tooling that it is unrelated to github.com/docker/swarmkit v1.12.0 and therefore the tag will not be considered by the MVS algorithm. Anyone working on projects with pre-module Swarmkit dependencies will not be disrupted, and projects can opt into migrating to module-enabled Swarmkit at their leisure. Greenfield projects can be prevented from importing an old version of Swarmkit by committing a go.mod file marked as deprecated to docker/swarmkit and tagging it e.g. v1.99.0.

Since you're planning to move the repo, you could make a clean break by intentionally breaking redirections from docker/swarmkit to the new location:

1. Move the GitHub repo to its new location
2. Fork it back to docker/swarmkit
3. Commit a deprecation go.mod file and archive the docker/swarmkit repo

Alternatively, you could bump the major version. github.com/docker/swarmkit/v2 is a distinct module, so Go module tooling will ignore the v1.12.0 tag since the major-version part does not match.

---

🔥 Hot take 🔥

The v1.12.0 tag was created pre go modules, and was never intended to be a "release".

The annotation message on the v1.12.0 tag is Tag version of swarmkit shipped in Docker 1.12.0. That is a textbook definition of a release: code which is deployed to production.

there are no plans to start tagging releases of this project

Why not? Commits of this project have implicitly been released every time the requirement was bumped in docker/cli and moby/moby. Tagging the releases going forward would merely make it explicit, while solving all the problems caused by the presence of the v1.12.0 tag and not making new problems for anyone outside the project.