From c5e9462651c8ff8a13cd4418c2bb7772f7acb04b Mon Sep 17 00:00:00 2001 From: anmol0705 Date: Mon, 14 Sep 2026 12:03:22 +0530 Subject: [PATCH] docs: clarify client- vs server-side evaluation of command annotations Add doc comments at the points where the experimentalCLI, swarm, and ostype command/flag annotations are checked, noting whether each is a client-side/build-time check (experimentalCLI) or evaluated against the connected daemon's reported state (swarm, ostype). No behavior change. Ref #1363 Signed-off-by: anmol0705 --- cli/cobra.go | 10 ++++++++++ cmd/docker/docker.go | 11 +++++++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/cli/cobra.go b/cli/cobra.go index bfcb1bdcc8f2..02e1d2d4b628 100644 --- a/cli/cobra.go +++ b/cli/cobra.go @@ -185,6 +185,10 @@ var helpCommand = &cobra.Command{ }, } +// isExperimental reports whether cmd (or one of its parents) carries the +// "experimentalCLI" annotation. This is a client-side, build-time check: +// it only inspects the static Annotations map and never consults a +// connected daemon. func isExperimental(cmd *cobra.Command) bool { if _, ok := cmd.Annotations["experimentalCLI"]; ok { return true @@ -330,6 +334,12 @@ func vendorAndVersion(cmd *cobra.Command) string { return "" } +// managementSubCommands and orchestratorSubCommands (below) group +// sub-commands by the "swarm" annotation for help-text display. The +// annotation itself is evaluated server-side elsewhere: a command's +// swarm-related behavior/availability is checked against the connected +// daemon's reported swarm state (see ServerInfo/SwarmStatus), not this +// static annotation lookup. func managementSubCommands(cmd *cobra.Command) []*cobra.Command { cmds := []*cobra.Command{} for _, sub := range allManagementSubCommands(cmd) { diff --git a/cmd/docker/docker.go b/cmd/docker/docker.go index 2341570b91a1..8ef2580551d4 100644 --- a/cmd/docker/docker.go +++ b/cmd/docker/docker.go @@ -628,8 +628,11 @@ func hideSubcommandIf(subcmd *cobra.Command, condition func(string) bool, annota func hideUnsupportedFeatures(cmd *cobra.Command, details versionDetails) { var ( notExperimental = func(_ string) bool { return !details.ServerInfo().HasExperimental } - notOSType = func(v string) bool { return details.ServerInfo().OSType != "" && v != details.ServerInfo().OSType } - notSwarmStatus = func(v string) bool { + // notOSType implements the server-side check for the "ostype" annotation: + // it hides flags/commands whose "ostype" value doesn't match the + // connected daemon's reported ServerInfo().OSType. + notOSType = func(v string) bool { return details.ServerInfo().OSType != "" && v != details.ServerInfo().OSType } + notSwarmStatus = func(v string) bool { s := details.ServerInfo().SwarmStatus if s == nil { // engine did not return swarm status header @@ -775,6 +778,10 @@ func isVersionSupported(f *pflag.Flag, clientVersion string) bool { return true } +// isOSTypeSupported checks the "ostype" flag annotation against osType, +// which callers pass as the connected daemon's ServerInfo().OSType. This +// makes "ostype" a server-side check: it depends on the daemon's reported +// OS, not on any client-side/build-time state. func isOSTypeSupported(f *pflag.Flag, osType string) bool { if v := getFlagAnnotation(f, "ostype"); v != "" && osType != "" { return osType == v