api: info: deprecate "Commit.Expected" fields

The `Commit` type was introduced in 2790ac68b3,
to assist triaging issues that were reported with an incorrect version of
runc or containerd. At the time, both `runc` and `containerd` were not yet
stable, and had to be built from a specific commit to guarantee compatibility.

We encountered various situations where unexpected (and incompatible) versions
of those binaries were packaged, resulting in hard to trace bug-reports.
For those situations, a "expected" version was set at compile time, to
indicate if the version installed was different from the expected version;

    docker info
    ...
    runc version: a592beb5bc4c4092b1b1bac971afed27687340c5 (expected: 69663f0bd4b60df09991c08812a60108003fa340)

Both `runc` and `containerd` are stable now, and docker 19.03 and up set the
expected version to the actual version since c65f0bd13c
and 23.0 did the same for the `init` binary b585c64e2b,
to prevent the CLI from reporting "unexpected version".

In short; the `Expected` fields no longer serves a real purpose.

In future, we can even consider deprecating the `ContainerdCommit`, `RuncCommit`
and `InitCommit` fields on the `/info` response (as we also include this
information as part of the components returned in `/version`), but those
can still be useful currently for situations where a user only provides
`docker info` output.

This patch starts with deprecating the `Expected` field.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

api/server/router/system/system_routes.go

@@ -100,6 +100,12 @@ func (s *systemRouter) getInfo(ctx context.Context, w http.ResponseWriter, r *ht
 			// Containerd field introduced in API v1.46.
 			info.Containerd = nil
 		}
+
+		// TODO(thaJeztah): Expected commits are deprecated, and should no longer be set in API 1.49.
+		info.ContainerdCommit.Expected = info.ContainerdCommit.ID //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
+		info.RuncCommit.Expected = info.RuncCommit.ID             //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
+		info.InitCommit.Expected = info.InitCommit.ID             //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
+
 		if versions.GreaterThanOrEqualTo(version, "1.42") {
 			info.KernelMemory = false
 		}

api/swagger.yaml

@@ -6170,6 +6170,8 @@ definitions:
       Expected:
         description: |
           Commit ID of external tool expected by dockerd as set at build time.
+
+          **Deprecated**: This field is deprecated and will be omitted in a API v1.49.
         type: "string"
         example: "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
 

api/types/system/info.go

@@ -137,8 +137,13 @@ type PluginsInfo struct {
 // Commit holds the Git-commit (SHA1) that a binary was built from, as reported
 // in the version-string of external tools, such as containerd, or runC.
 type Commit struct {
-	ID       string // ID is the actual commit ID of external tool.
-	Expected string // Expected is the commit ID of external tool expected by dockerd as set at build time.
+	// ID is the actual commit ID or version of external tool.
+	ID string
+
+	// Expected is the commit ID of external tool expected by dockerd as set at build time.
+	//
+	// Deprecated: this field is no longer used in API v1.49, but kept for backward-compatibility with older API versions.
+	Expected string
 }
 
 // NetworkAddressPool is a temp struct used by [Info] struct.

daemon/info_unix.go

@@ -196,7 +196,6 @@ func populateRuncCommit(v *system.Commit, cfg *configStore) error {
 		return err
 	}
 	v.ID = commit
-	v.Expected = commit
 	return nil
 }
 
@@ -223,7 +222,6 @@ func (daemon *Daemon) populateInitCommit(ctx context.Context, v *system.Info, cf
 		return nil
 	}
 	v.InitCommit.ID = commit
-	v.InitCommit.Expected = v.InitCommit.ID
 	return nil
 }
 
@@ -437,7 +435,6 @@ func (daemon *Daemon) populateContainerdCommit(ctx context.Context, v *system.Co
 		return nil
 	}
 	v.ID = rv.Revision
-	v.Expected = rv.Revision
 	return nil
 }
 

docs/api/version-history.md

@@ -24,6 +24,9 @@ keywords: "API, Docker, rcli, REST, documentation"
   `platform` parameter (JSON encoded OCI Platform type) that allows to specify
   a platform to load/save. Not passing this parameter will result in
   loading/saving the full multi-platform image.
+* Deprecated: The `ContainerdCommit.Expected`, `RuncCommit.Expected`, and
+  `InitCommit.Expected` fields in the `GET /info` endpoint are deprecated
+  and will be omitted in API v1.49.
 
 ## v1.47 API changes
 

integration/system/info_linux_test.go

@@ -17,11 +17,11 @@ func TestInfoBinaryCommits(t *testing.T) {
 	assert.NilError(t, err)
 
 	assert.Check(t, "N/A" != info.ContainerdCommit.ID)
-	assert.Check(t, is.Equal(info.ContainerdCommit.Expected, info.ContainerdCommit.ID))
+	assert.Check(t, is.Equal(info.ContainerdCommit.Expected, info.ContainerdCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
 
 	assert.Check(t, "N/A" != info.InitCommit.ID)
-	assert.Check(t, is.Equal(info.InitCommit.Expected, info.InitCommit.ID))
+	assert.Check(t, is.Equal(info.InitCommit.Expected, info.InitCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
 
 	assert.Check(t, "N/A" != info.RuncCommit.ID)
-	assert.Check(t, is.Equal(info.RuncCommit.Expected, info.RuncCommit.ID))
+	assert.Check(t, is.Equal(info.RuncCommit.Expected, info.RuncCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
 }