Merge pull request #29078 from timhoffm/doc-discourage

QuLogic · web-flow · commit 0bd61f663e1a · 2024-11-05T18:16:03.000-05:00
Document how to discourage API
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -239,3 +239,20 @@ What's new notes
 .. include:: ../users/next_whats_new/README.rst
    :start-after: whats-new-guide-start
    :end-before: whats-new-guide-end
+
+Discourage API
+--------------
+
+We have API that we do not recommend anymore for new code, but that cannot be
+deprecated because its removal would be breaking backward-compatibility and too
+disruptive. In such a case we can formally discourage API. This can cover
+specific parameters, call patterns, whole methods etc.
+
+To do so, add a note to the docstring ::
+
+    .. admonition:: Discouraged
+
+       [description and suggested alternative]
+
+You find several examples for good descriptions if you search the codebase for
+``.. admonition:: Discouraged``.
