Added best practices for versionadded/changed annotations.

3 files changed, 44 insertions, 1 deletions

diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 7bc37f5a75..965ce45eaa 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/docs/internals/contributing/writing-code/submitting-patches.txt
@@ -320,7 +320,8 @@ New Features
 
 * Are there tests to "exercise" all of the new code?
 * Is there a release note in ``docs/releases/A.B.txt``?
-* Is there documentation for the feature and is it annotated appropriately with
+* Is there documentation for the feature and is it :ref:`annotated
+  appropriately <documenting-new-features>` with
   ``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``?
 
 Deprecating a feature
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index aec51b0742..a08d07eae5 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -216,6 +216,46 @@ General improvements, or other changes to the APIs that should be emphasized
 should use the "``.. versionchanged:: X.Y``" directive (with the same format
 as the ``versionadded`` mentioned above.
 
+These ``versionadded`` and ``versionchanged`` blocks should be "self-contained."
+In other words, since we only keep these annotations around for two releases,
+it's nice to be able to remove the annotation and its contents without having
+to reflow, reindent, or edit the surrounding text. For example, instead of
+putting the entire description of a new or changed feature in a block, do
+something like this::
+
+    .. class:: Author(first_name, last_name, middle_name=None)
+
+        A person who writes books.
+
+        ``first_name`` is ...
+
+        ...
+
+        ``middle_name`` is ...
+
+        .. versionchanged:: A.B
+
+            The ``middle_name`` argument was added.
+
+Put the changed annotation notes at the bottom of a section, not the top.
+
+Also, avoid referring to a specific version of Django outside a
+``versionadded`` or ``versionchanged`` block. Even inside a block, it's often
+redundant to do so as these annotations render as "New in Django A.B:" and
+"Changed in Django A.B", respectively.
+
+If a function, attribute, etc. is added, it's also okay to use a
+``versionadded`` annotation like this::
+
+    .. attribute:: Author.middle_name
+
+        .. versionadded:: A.B
+
+        An author's middle name.
+
+We can simply remove the ``.. versionadded:: A.B`` annotation without any
+indentation changes when the time comes.
+
 An example
 ----------
 
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index 8c44d77f79..507e4f15c2 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -515,9 +515,11 @@ refactored
 refactorings
 refactors
 referer
+reflow
 regex
 regexes
 reimplement
+reindent
 reindex
 releasers
 removetags