[28.x backport] cli/command/stack/*: deprecate exported functions and types

.golangci.yml

@@ -222,6 +222,14 @@ linters:
         linters:
           - staticcheck
 
+      # Ignore deprecation linting for cli/command/stack/*.
+      #
+      # FIXME(thaJeztah): remove exception once these functions are un-exported or internal; see https://github.com/docker/cli/pull/6389
+      - text: '^(SA1019): '
+        path: "cli/command/stack"
+        linters:
+          - staticcheck
+
     # Log a warning if an exclusion rule is unused.
     # Default: false
     warn-unused: true

cli/command/stack/formatter/formatter.go

@@ -8,21 +8,31 @@ import (
 
 const (
 	// SwarmStackTableFormat is the default Swarm stack format
+	//
+	// Deprecated: this type was for internal use and will be removed in the next release.
 	SwarmStackTableFormat formatter.Format = "table {{.Name}}\t{{.Services}}"
 
 	stackServicesHeader = "SERVICES"
 
 	// TableFormatKey is an alias for formatter.TableFormatKey
+	//
+	// Deprecated: this type was for internal use and will be removed in the next release.
 	TableFormatKey = formatter.TableFormatKey
 )
 
 // Context is an alias for formatter.Context
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Context = formatter.Context
 
 // Format is an alias for formatter.Format
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Format = formatter.Format
 
 // Stack contains deployed stack information.
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Stack struct {
 	// Name is the name of the stack
 	Name string
@@ -31,6 +41,8 @@ type Stack struct {
 }
 
 // StackWrite writes formatted stacks using the Context
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func StackWrite(ctx formatter.Context, stacks []*Stack) error {
 	render := func(format func(subContext formatter.SubContext) error) error {
 		for _, stack := range stacks {

cli/command/stack/list.go

@@ -16,16 +16,18 @@ import (
 	"github.com/spf13/cobra"
 )
 
+type listOptions = options.List
+
 func newListCommand(dockerCli command.Cli) *cobra.Command {
-	opts := options.List{}
+	opts := listOptions{}
 
 	cmd := &cobra.Command{
 		Use:     "ls [OPTIONS]",
 		Aliases: []string{"list"},
 		Short:   "List stacks",
 		Args:    cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return RunList(cmd.Context(), dockerCli, opts)
+			return runList(cmd.Context(), dockerCli, opts)
 		},
 		ValidArgsFunction: completion.NoComplete,
 	}
@@ -36,17 +38,24 @@ func newListCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunList performs a stack list against the specified swarm cluster
-func RunList(ctx context.Context, dockerCli command.Cli, opts options.List) error {
-	ss, err := swarm.GetStacks(ctx, dockerCli.Client())
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
+func RunList(ctx context.Context, dockerCLI command.Cli, opts options.List) error {
+	return runList(ctx, dockerCLI, opts)
+}
+
+// runList performs a stack list against the specified swarm cluster
+func runList(ctx context.Context, dockerCLI command.Cli, opts listOptions) error {
+	ss, err := swarm.GetStacks(ctx, dockerCLI.Client())
 	if err != nil {
 		return err
 	}
 	stacks := make([]*formatter.Stack, 0, len(ss))
 	stacks = append(stacks, ss...)
-	return format(dockerCli.Out(), opts, stacks)
+	return format(dockerCLI.Out(), opts, stacks)
 }
 
-func format(out io.Writer, opts options.List, stacks []*formatter.Stack) error {
+func format(out io.Writer, opts listOptions, stacks []*formatter.Stack) error {
 	fmt := formatter.Format(opts.Format)
 	if fmt == "" || fmt == formatter.TableFormatKey {
 		fmt = formatter.SwarmStackTableFormat

cli/command/stack/loader/loader.go

@@ -22,6 +22,8 @@ import (
 )
 
 // LoadComposefile parse the composefile specified in the cli and returns its Config and version.
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func LoadComposefile(dockerCli command.Cli, opts options.Deploy) (*composetypes.Config, error) {
 	configDetails, err := GetConfigDetails(opts.Composefiles, dockerCli.In())
 	if err != nil {
@@ -84,6 +86,8 @@ func propertyWarnings(properties map[string]string) string {
 }
 
 // GetConfigDetails parse the composefiles specified in the cli and returns their ConfigDetails
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func GetConfigDetails(composefiles []string, stdin io.Reader) (composetypes.ConfigDetails, error) {
 	var details composetypes.ConfigDetails
 

cli/command/stack/options/opts.go

@@ -3,6 +3,8 @@ package options
 import "github.com/docker/cli/opts"
 
 // Deploy holds docker stack deploy options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Deploy struct {
 	Composefiles     []string
 	Namespace        string
@@ -14,18 +16,24 @@ type Deploy struct {
 }
 
 // Config holds docker stack config options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Config struct {
 	Composefiles      []string
 	SkipInterpolation bool
 }
 
 // List holds docker stack ls options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type List struct {
 	Format        string
 	AllNamespaces bool
 }
 
 // PS holds docker stack ps options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type PS struct {
 	Filter    opts.FilterOpt
 	NoTrunc   bool
@@ -36,12 +44,16 @@ type PS struct {
 }
 
 // Remove holds docker stack remove options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Remove struct {
 	Namespaces []string
 	Detach     bool
 }
 
 // Services holds docker stack services options
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type Services struct {
 	Quiet     bool
 	Format    string

cli/command/stack/services.go

@@ -18,8 +18,11 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newServicesCommand(dockerCli command.Cli) *cobra.Command {
-	opts := options.Services{Filter: cliopts.NewFilterOpt()}
+// servicesOptions holds docker stack services options
+type servicesOptions = options.Services
+
+func newServicesCommand(dockerCLI command.Cli) *cobra.Command {
+	opts := servicesOptions{Filter: cliopts.NewFilterOpt()}
 
 	cmd := &cobra.Command{
 		Use:   "services [OPTIONS] STACK",
@@ -30,10 +33,10 @@ func newServicesCommand(dockerCli command.Cli) *cobra.Command {
 			if err := validateStackName(opts.Namespace); err != nil {
 				return err
 			}
-			return RunServices(cmd.Context(), dockerCli, opts)
+			return runServices(cmd.Context(), dockerCLI, opts)
 		},
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-			return completeNames(dockerCli)(cmd, args, toComplete)
+			return completeNames(dockerCLI)(cmd, args, toComplete)
 		},
 	}
 	flags := cmd.Flags()
@@ -44,15 +47,22 @@ func newServicesCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunServices performs a stack services against the specified swarm cluster
-func RunServices(ctx context.Context, dockerCli command.Cli, opts options.Services) error {
-	services, err := swarm.GetServices(ctx, dockerCli, opts)
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
+func RunServices(ctx context.Context, dockerCLI command.Cli, opts options.Services) error {
+	return runServices(ctx, dockerCLI, opts)
+}
+
+// runServices performs a stack services against the specified swarm cluster
+func runServices(ctx context.Context, dockerCLI command.Cli, opts servicesOptions) error {
+	services, err := swarm.GetServices(ctx, dockerCLI, opts)
 	if err != nil {
 		return err
 	}
-	return formatWrite(dockerCli, services, opts)
+	return formatWrite(dockerCLI, services, opts)
 }
 
-func formatWrite(dockerCLI command.Cli, services []swarmtypes.Service, opts options.Services) error {
+func formatWrite(dockerCLI command.Cli, services []swarmtypes.Service, opts servicesOptions) error {
 	// if no services in the stack, print message and exit 0
 	if len(services) == 0 {
 		_, _ = fmt.Fprintln(dockerCLI.Err(), "Nothing found in stack:", opts.Namespace)

cli/command/stack/swarm/deploy.go

@@ -23,6 +23,8 @@ const (
 )
 
 // RunDeploy is the swarm implementation of docker stack deploy
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func RunDeploy(ctx context.Context, dockerCLI command.Cli, flags *pflag.FlagSet, opts *options.Deploy, cfg *composetypes.Config) error {
 	if err := validateResolveImageFlag(opts); err != nil {
 		return err

cli/command/stack/swarm/list.go

@@ -11,6 +11,8 @@ import (
 )
 
 // GetStacks lists the swarm stacks.
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func GetStacks(ctx context.Context, apiClient client.ServiceAPIClient) ([]*formatter.Stack, error) {
 	services, err := apiClient.ServiceList(
 		ctx,

cli/command/stack/swarm/ps.go

@@ -12,6 +12,8 @@ import (
 )
 
 // RunPS is the swarm implementation of docker stack ps
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func RunPS(ctx context.Context, dockerCLI command.Cli, opts options.PS) error {
 	filter := getStackFilterFromOpt(opts.Namespace, opts.Filter)
 

cli/command/stack/swarm/remove.go

@@ -15,6 +15,8 @@ import (
 )
 
 // RunRemove is the swarm implementation of docker stack remove
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
 func RunRemove(ctx context.Context, dockerCli command.Cli, opts options.Remove) error {
 	apiClient := dockerCli.Client()
 

cli/command/stack/swarm/services.go

@@ -10,10 +10,12 @@ import (
 )
 
 // GetServices is the swarm implementation of listing stack services
-func GetServices(ctx context.Context, dockerCli command.Cli, opts options.Services) ([]swarm.Service, error) {
+//
+// Deprecated: this function was for internal use and will be removed in the next release.
+func GetServices(ctx context.Context, dockerCLI command.Cli, opts options.Services) ([]swarm.Service, error) {
 	var (
-		err    error
-		client = dockerCli.Client()
+		err       error
+		apiClient = dockerCLI.Client()
 	)
 
 	listOpts := swarm.ServiceListOptions{
@@ -25,7 +27,7 @@ func GetServices(ctx context.Context, dockerCli command.Cli, opts options.Servic
 		Status: !opts.Quiet,
 	}
 
-	services, err := client.ServiceList(ctx, listOpts)
+	services, err := apiClient.ServiceList(ctx, listOpts)
 	if err != nil {
 		return nil, err
 	}
@@ -43,7 +45,7 @@ func GetServices(ctx context.Context, dockerCli command.Cli, opts options.Servic
 		// situations where the client uses the "default" version. To account for
 		// these situations, we do a quick check for services that do not have
 		// a ServiceStatus set, and perform a lookup for those.
-		services, err = service.AppendServiceStatus(ctx, client, services)
+		services, err = service.AppendServiceStatus(ctx, apiClient, services)
 		if err != nil {
 			return nil, err
 		}