Clarify resource deprecation process

The deprecation process is unclear in that it does not specify the goals of
hiding (rather than removing) obsolete resource types. This has led to
resources being hidden without removing their implementation, leaving
existing stacks potentially inoperable.

State clearly the purpose of hidden resource types, and options available
to help users migrate.

Change-Id: I7362c094122066f98a5c95d4c5da16cb5a5c1108

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/source/developing_guides/supportstatus.rst b/doc/source/developing_guides/supportstatus.rst
index 0c084220f..ef49459b6 100644
--- a/doc/source/developing_guides/supportstatus.rst
+++ b/doc/source/developing_guides/supportstatus.rst
@@ -107,6 +107,14 @@ object from documentation and from result of :code:`resource-type-list` CLI
 command, if object is resource. Also, :code:`resource-type-show` command with
 such resource will raise `NotSupported` exception.
 
+The purpose of hiding, rather than removing, obsolete resources or properties
+is to ensure that users can continue to operate existing stacks - replacing or
+removing the offending resources, or deleting the entire stack. Steps should be
+taken to ensure that these operations can succeed, e.g. by replacing a hidden
+resource type's implementation with one that is equivalent to
+``OS::Heat::None`` when the underlying API no longer exists, supplying a
+*substitute_class* for a resource type, or adding a property translation rule.
+
 Using Support Status during code writing
 ----------------------------------------
 When adding new objects or adding objects instead of some old (e.g. property