diff --git a/doc/source/contributor/api_microversion_dev.rst b/doc/source/contributor/api_microversion_dev.rst
index 1f5a0cbe185..ece465c2888 100644
--- a/doc/source/contributor/api_microversion_dev.rst
+++ b/doc/source/contributor/api_microversion_dev.rst
@@ -126,6 +126,11 @@ we need a microversion".
    {rank=min; silent_fail}
    }
 
+If a patch that will require a microversion increment is proposed
+having similar intention and code with a previously merged patch
+given the previous merged patch hasn't been released, then the
+previously merged patch could be modified to include the new patch
+code under the same microversion.
 
 **Footnotes**
 
@@ -289,6 +294,11 @@ necessary to add changes to other places which describe your change:
   should indicate which microversion is required for the change, and it should
   refer to the numerical value of the microversion and not its constant name.
 
+* Update the ``version`` parameter in api-ref responses here ``cinder/api-ref/
+  source/v3/samples/versions/version-show-response.json`` and here
+  ``cinder/api-ref/source/v3/samples/versions/versions-response.json``
+  to the latest microversion to avoid functional test failure.
+
 Allocating a microversion
 -------------------------