feat(push): deprecate --ignore-push-failures in favor of --ignore-missing

cmd/compose/push.go

@@ -52,6 +52,8 @@ func pushCommand(p *ProjectOptions, dockerCli command.Cli, backendOptions *Backe
 	pushCmd.Flags().BoolVar(&opts.IgnoreMissing, "ignore-missing", false, "Skip images that are not available locally instead of failing to push them")
 	pushCmd.Flags().BoolVar(&opts.IncludeDeps, "include-deps", false, "Also push images of services declared as dependencies")
 	pushCmd.Flags().BoolVarP(&opts.Quiet, "quiet", "q", false, "Push without printing progress information")
+	pushCmd.Flags().MarkDeprecated("ignore-push-failures", "use --ignore-missing to skip images that are not available locally") //nolint:errcheck
+	pushCmd.MarkFlagsMutuallyExclusive("ignore-push-failures", "ignore-missing")
 
 	return pushCmd
 }

cmd/compose/push_test.go

@@ -0,0 +1,64 @@
+/*
+   Copyright 2026 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package compose
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"gotest.tools/v3/assert"
+)
+
+func TestPushIgnorePushFailuresIsNotDiscoverable(t *testing.T) {
+	cmd := pushCommand(&ProjectOptions{}, nil, &BackendOptions{})
+	assert.Assert(t, !strings.Contains(cmd.UsageString(), "ignore-push-failures"))
+}
+
+// The real push command is run with RunE stubbed out, so only flag parsing
+// and validation are exercised.
+func TestPushIgnoreFlags(t *testing.T) {
+	tests := []struct {
+		name        string
+		args        []string
+		wantWarning bool
+		wantErr     string
+	}{
+		{name: "ignore-push-failures is deprecated but usable", args: []string{"--ignore-push-failures"}, wantWarning: true},
+		{name: "ignore-missing alone", args: []string{"--ignore-missing"}},
+		{name: "both flags are mutually exclusive", args: []string{"--ignore-push-failures", "--ignore-missing"}, wantWarning: true, wantErr: "none of the others can be"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := pushCommand(&ProjectOptions{}, nil, &BackendOptions{})
+			cmd.RunE = func(*cobra.Command, []string) error { return nil }
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetErr(&out)
+			cmd.SetArgs(tt.args)
+
+			err := cmd.ExecuteContext(t.Context())
+			if tt.wantErr == "" {
+				assert.NilError(t, err)
+			} else {
+				assert.ErrorContains(t, err, tt.wantErr)
+			}
+			assert.Equal(t, strings.Contains(out.String(), "--ignore-push-failures has been deprecated"), tt.wantWarning, out.String())
+		})
+	}
+}

docs/reference/compose_push.md

@@ -22,13 +22,12 @@ services:
 
 ### Options
 
-| Name                     | Type   | Default | Description                                                                |
-|:-------------------------|:-------|:--------|:---------------------------------------------------------------------------|
-| `--dry-run`              | `bool` |         | Execute command in dry run mode                                            |
-| `--ignore-missing`       | `bool` |         | Skip images that are not available locally instead of failing to push them |
-| `--ignore-push-failures` | `bool` |         | Push what it can and ignores images with push failures                     |
-| `--include-deps`         | `bool` |         | Also push images of services declared as dependencies                      |
-| `-q`, `--quiet`          | `bool` |         | Push without printing progress information                                 |
+| Name               | Type   | Default | Description                                                                |
+|:-------------------|:-------|:--------|:---------------------------------------------------------------------------|
+| `--dry-run`        | `bool` |         | Execute command in dry run mode                                            |
+| `--ignore-missing` | `bool` |         | Skip images that are not available locally instead of failing to push them |
+| `--include-deps`   | `bool` |         | Also push images of services declared as dependencies                      |
+| `-q`, `--quiet`    | `bool` |         | Push without printing progress information                                 |
 
 
 <!---MARKER_GEN_END-->

docs/reference/docker_compose_push.yaml

@@ -38,8 +38,8 @@ options:
       value_type: bool
       default_value: "false"
       description: Push what it can and ignores images with push failures
-      deprecated: false
-      hidden: false
+      deprecated: true
+      hidden: true
       experimental: false
       experimentalcli: false
       kubernetes: false