dotcloud/docker — pull request #5088 by shykes (2014-04-08 17:05:19+00:00)
Title: Early deprecation warning for 'docker commit --run'

Warn users of the planned deprecation of 'docker commit --run', and hide
it from the docs and usage message. The option continues to work.

Note that an alternative to 'commit --run' is being implemented but is
not yet available. We are printing the warning anyway because on
the basis that it never hurts to give more advance warning.

The 'commit --run' flag is a leftover from the very early days of Docker,
and has several problems:

1) It is very user unfriendly. You have to pass a literal json dict
which is poorly documented and changes regularly (see PortSpecs vs
ExposedPorts). The merge behavior is not clear and also changes
regularly. it's not possible to unset a value.

2) It overlaps with the Dockerfile syntax. There are 2 ways to set
a default command, expose a port or change an env variable. Some
things can be done in a Dockerfile but not in --run. Some things
can be done in --run but not in a Dockerfile. It would be better
to push a single syntax, allow using it both in a file and via
the command line, and make improvements in a single place.

3) It exposes data structures which should not be publicly exposed.
There are several planned improvements to Docker which require moving
around the content and schema of the various Config, Image and Container
structures. The less of those we expose in public interfaces, the easier
it is to move things around without a reverse compatibility nightmare.

Docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes)