deprecate "--pause" flag on docker commit in favor of "--no-pause"

Commit [moby@17d870b] (API v1.13, docker v1.1.0) changed the default to pause
containers during commit, keeping the behavior opt-in for older API versions.
This version-gate was removed in [moby@1b1147e] because API versions lower
than v1.23 were no longer supported.

This patch deprecates the `--pause` flag in favor of a `--no-pause` flag to
be more explicit on the default. The old `--pause` flag is marked deprecated
but still functional. Using the deprecated flag will print a warning, and an
error is produced when trying to use both the old and new flag;

    docker commit --pause mycontainer
    Flag --pause has been deprecated, and enabled by default. Use --no-pause to disable pausing during commit.

    docker commit --pause=false mycontainer
    Flag --pause has been deprecated, and enabled by default. Use --no-pause to disable pausing during commit.

    docker commit --pause --no-pause mycontainer
    Flag --pause has been deprecated, use --no-pause instead
    conflicting options: --no-pause and --pause cannot be used together

[moby@17d870b]: https://github.com/moby/moby/commit/17d870bed5ef997c30da1e8b9843f4e84202f8d4
[moby@1b1147e]: https://github.com/moby/moby/commit/1b1147e46b732caeaed4ae365cd56ccbfdf40233

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

cli/command/container/commit.go

@@ -2,6 +2,7 @@ package container
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	"github.com/docker/cli/cli"
@@ -17,6 +18,7 @@ type commitOptions struct {
 	reference string
 
 	pause   bool
+	noPause bool
 	comment string
 	author  string
 	changes opts.ListOpts
@@ -35,6 +37,12 @@ func newCommitCommand(dockerCLI command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				options.reference = args[1]
 			}
+			if cmd.Flag("pause").Changed {
+				if cmd.Flag("no-pause").Changed {
+					return errors.New("conflicting options: --no-pause and --pause cannot be used together")
+				}
+				options.noPause = !options.pause
+			}
 			return runCommit(cmd.Context(), dockerCLI, &options)
 		},
 		Annotations: map[string]string{
@@ -47,7 +55,11 @@ func newCommitCommand(dockerCLI command.Cli) *cobra.Command {
 	flags := cmd.Flags()
 	flags.SetInterspersed(false)
 
-	flags.BoolVarP(&options.pause, "pause", "p", true, "Pause container during commit")
+	// TODO(thaJeztah): Deprecated: the --pause flag was deprecated in v29 and can be removed in v30.
+	flags.BoolVarP(&options.pause, "pause", "p", true, "Pause container during commit (deprecated: use --no-pause instead)")
+	_ = flags.MarkDeprecated("pause", "and enabled by default. Use --no-pause to disable pausing during commit.")
+
+	flags.BoolVar(&options.noPause, "no-pause", false, "Disable pausing container during commit")
 	flags.StringVarP(&options.comment, "message", "m", "", "Commit message")
 	flags.StringVarP(&options.author, "author", "a", "", `Author (e.g., "John Hannibal Smith <hannibal@a-team.com>")`)
 
@@ -63,12 +75,12 @@ func runCommit(ctx context.Context, dockerCli command.Cli, options *commitOption
 		Comment:   options.comment,
 		Author:    options.author,
 		Changes:   options.changes.GetSlice(),
-		Pause:     options.pause,
+		Pause:     !options.noPause,
 	})
 	if err != nil {
 		return err
 	}
 
-	fmt.Fprintln(dockerCli.Out(), response.ID)
+	_, _ = fmt.Fprintln(dockerCli.Out(), response.ID)
 	return nil
 }

cli/command/container/commit_test.go

@@ -37,7 +37,7 @@ func TestRunCommit(t *testing.T) {
 			"--author", "Author Name <author@name.com>",
 			"--change", "EXPOSE 80",
 			"--message", "commit message",
-			"--pause=false",
+			"--no-pause",
 			"container-id",
 		},
 	)

docs/deprecated.md

@@ -53,6 +53,7 @@ The following table provides an overview of the current status of deprecated fea
 
 | Status     | Feature                                                                                                                            | Deprecated | Remove |
 |------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
+| Deprecated | [`--pause` option on `docker commit`](#--pause-option-on-docker-commit)                                                            | v29.0      | v30.0  |
 | Deprecated | [Legacy links environment variables](#legacy-links-environment-variables)                                                          | v28.4      | v30.0  |
 | Deprecated | [Special handling for quoted values for TLS flags](#special-handling-for-quoted-values-for-tls-flags)                              | v28.4      | v29.0  |
 | Deprecated | [Empty/nil fields in image Config from inspect API](#emptynil-fields-in-image-config-from-inspect-api)                             | v28.3      | v29.0  |
@@ -124,6 +125,19 @@ The following table provides an overview of the current status of deprecated fea
 | Removed    | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit)                                                                    | v0.10      | v1.13  |
 | Removed    | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import)                                                  | v0.6.7     | v1.12  |
 
+### `--pause` option on `docker commit`
+
+**Deprecated in release: v29.0**
+
+**Target for removal in release: v30.0**
+
+The `--pause` option is enabled by default since Docker v1.1.0 to prevent
+committing containers in an inconsistent state, but can be disabled by
+setting the `--pause=false` option. In docker CLI v29.0 this flag is
+replaced by a `--no-pause` flag instead. The `--pause` option is still
+functional in the v29.0 release, printing a deprecation warning, but
+will be removed in docker CLI v30.
+
 ### Legacy links environment variables
 
 **Deprecated in release: v28.4**

docs/reference/commandline/commit.md

@@ -14,7 +14,7 @@ Create a new image from a container's changes
 | `-a`, `--author`  | `string` |         | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
 | `-c`, `--change`  | `list`   |         | Apply Dockerfile instruction to the created image          |
 | `-m`, `--message` | `string` |         | Commit message                                             |
-| `-p`, `--pause`   | `bool`   | `true`  | Pause container during commit                              |
+| `--no-pause`      | `bool`   |         | Disable pausing container during commit                    |
 
 
 <!---MARKER_GEN_END-->

docs/reference/commandline/container_commit.md

@@ -14,7 +14,7 @@ Create a new image from a container's changes
 | `-a`, `--author`                       | `string` |         | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
 | [`-c`](#change), [`--change`](#change) | `list`   |         | Apply Dockerfile instruction to the created image          |
 | `-m`, `--message`                      | `string` |         | Commit message                                             |
-| `-p`, `--pause`                        | `bool`   | `true`  | Pause container during commit                              |
+| `--no-pause`                           | `bool`   |         | Disable pausing container during commit                    |
 
 
 <!---MARKER_GEN_END-->