bpo-39879: Update datamodel docs to include dict ordering (GH-19006)

AkechiShiro · furkanonder · web-flow · commit 59c644eaa72b · 2020-03-26T09:54:04.000-05:00
Co-authored-by: furkanonder &lt;furkantahaonder@gmail.com&gt;
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
@@ -425,6 +425,11 @@ Mappings
       equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
       the same dictionary entry.
 
+      Dictionaries preserve insertion order, meaning that keys will be produced
+      in the same order they were added sequentially over the dictionary.
+      Replacing an existing key does not change the order, however removing a key
+      and re-inserting it will add it to the end instead of keeping its old place.
+
       Dictionaries are mutable; they can be created by the ``{...}`` notation (see
       section :ref:`dict`).
 
@@ -436,6 +441,11 @@ Mappings
       additional examples of mapping types, as does the :mod:`collections`
       module.
 
+      .. versionchanged:: 3.7
+         Dictionaries did not preserve insertion order in versions of Python before 3.6.
+         In CPython 3.6, insertion order was preserved, but it was considered
+         an implementation detail at that time rather than a language guarantee.
+
 Callable types
    .. index::
       object: callable
diff --git a/Misc/ACKS b/Misc/ACKS
@@ -39,6 +39,7 @@ Ray Allen
 Billy G. Allie
 Jamiel Almeida
 Kevin Altis
+Samy Lahfa
 Skyler Leigh Amador
 Joe Amenta
 Rose Ames
diff --git a/Misc/NEWS.d/next/Documentation/2020-03-16-18-12-02.bpo-39879.CnQ7Cv.rst b/Misc/NEWS.d/next/Documentation/2020-03-16-18-12-02.bpo-39879.CnQ7Cv.rst
@@ -0,0 +1,2 @@
+Updated :ref:`datamodel` docs to include :func:`dict` insertion order preservation.
+Patch by Furkan Onder and Samy Lahfa.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Updated :ref:`datamodel` docs to include :func:`dict` insertion order preservation.
	`2`	`+Patch by Furkan Onder and Samy Lahfa.`