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 ` 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