Add a doc that dictates backwards incompatible changes

start tracking any changes in a standard format, so users may
have a heads up about any impacts.

Change-Id: Ibc06926a53592e927d11440362cd3598e0d4b2bf
Closes-Bug: 1406470

2 files changed, 48 insertions, 0 deletions

diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst
new file mode 100644
index 00000000..817f2a30
--- /dev/null
+++ b/doc/source/backwards-incompatible.rst
@@ -0,0 +1,47 @@
+==============================
+Backwards Incompatible Changes
+==============================
+
+Despite our best efforts, sometimes the OpenStackClient team may introduce a
+backwards incompatible change. For user convenience we are tracking any such
+changes here (as of the 1.0.0 release).
+
+Should positional arguments for a command need to change, the OpenStackClient
+team attempts to make the transition as painless as possible. Look for
+deprecation warnings that indicate the new commands (or options) to use.
+
+List of Backwards Incompatible Changes
+======================================
+
+1. Rename command `openstack project usage list`
+
+  The `project` part of the command was pointless.
+
+  * In favor of: `openstack usage list` instead.
+  * As of: 1.0.2
+  * Removed in: TBD
+  * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1406654
+  * Commit: https://review.openstack.org/#/c/147379/
+
+2. <type> should not be optional for command `openstack service create`
+
+  Previously, the command was `openstack service create <name> --type <type>`,
+  whereas now it is: `openstack service create <type> --name <name>`
+  This bug also affected python-keystoneclient, and keystone.
+
+  * In favor of: making <type> a positional argument.
+  * As of: 1.0.2
+  * Removed in: TBD
+  * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1404073
+  * Commit: https://review.openstack.org/#/c/143242/
+
+For Developers
+==============
+
+If introducing a backwards incompatible change, then add the tag:
+``BackwardsIncompatibleImpact`` to your git commit message, and if possible,
+update this file.
+
+To review all changes that are affected, use the following query:
+
+https://review.openstack.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 7258a7b4..7a595479 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -18,6 +18,7 @@ Contents:
    authentication
    interactive
    humaninterfaceguide
+   backwards-incompatible
    releases
    man/openstack