Merge pull request #13900 from duglin/Deprecate

Define Docker's deprecation policy

docs/misc/deprecated.md

@@ -0,0 +1,58 @@
+<!--[metadata]>
++++
+title = "Docker Deprecated Features"
+description = "Deprecated Features."
+keywords = ["docker, documentation, about, technology, deprecate"]
+[menu.main]
+parent = "mn_use_docker"
++++
+<![end-metadata]-->
+
+# Deprecated Features
+
+The following list of features are deprecated.
+
+### Old Command Line Options
+**Deprecated In Release: [v1.8.0](/release-notes/#docker-engine-1-8-0)**
+
+**Target For Removal In Release: v1.10**
+
+The following single-dash (`-opt`) variant of certain command line options 
+are deprecated and replaced with double-dash options (`--opt`):
+
+    docker attach -nostdin
+    docker attach -sig-proxy
+    docker build -no-cache
+    docker build -rm
+    docker commit -author
+    docker commit -run
+    docker events -since
+    docker history -notrunc
+    docker images -notrunc
+    docker inspect -format
+    docker ps -beforeId
+    docker ps -notrunc
+    docker ps -sinceId
+    docker rm -link
+    docker run -cidfile
+    docker run -cpuset
+    docker run -dns
+    docker run -entrypoint
+    docker run -expose
+    docker run -link
+    docker run -lxc-conf
+    docker run -n
+    docker run -privileged
+    docker run -volumes-from
+    docker search -notrunc
+    docker search -stars
+    docker search -t
+    docker search -trusted
+    docker tag -force
+
+The following single-dash options are deprecated and have no replacement:
+
+    docker run --networking
+    docker ps --since-id
+    docker ps --before-id
+    docker search --trusted

docs/misc/index.md

@@ -97,6 +97,21 @@ implementation, check out the [Docker User Guide](/userguide/).
 A summary of the changes in each release in the current series can now be found
 on the separate [Release Notes page](/release-notes/)
 
+## Feature Deprecation Policy
+
+As changes are made to Docker there may be times when existing features
+will need to be removed or replace with newer features. Before an existing
+feature is removed it will be labeled as "deprecated" within the documentation
+and will remain in Docker for, usually, at least 2 releases. After that time
+it may be removed.
+
+Users are expected to take note of the list of deprecated features each
+release and plan their migration away from those features, and (if applicable)
+towards the replacement features as soon as possible.
+
+The complete list of deprecated features can be found on the
+[Deprecated Features page](deprecated).
+
 ## Licensing
 
 Docker is licensed under the Apache License, Version 2.0. See

docs/misc/release-notes.md

@@ -9,6 +9,17 @@ parent = "smn_release_notes"
 +++
 <![end-metadata]-->
 
+# Deprecated Features
+
+To see the complete list of deprecated features please see the
+[Deprecated Features](deprecated) page.
+
+# Removed Features
+
+The following features have been removed in this release:
+
+* None!
+
 # Release notes version 1.6.0
 (2015-04-16)