The Warnings section of the doctest documentation (https://docs.python.org/3.8/library/doctest.html#warnings) contains an example that the printing order of a dictionary is not guaranteed.  Since it is now guaranteed to be insertion order, perhaps the example should be changed.

To me, the question is whether to delete the dict example, or qualify it with "Before 3.7 (or 3.6 for CPython)" but leave the illustration of workarounds. Raymond, what do you thing?

Add a comment along the lines you (Terry) suggested.  Some people need to write doctests that run under many versions of Python, so the info is still supremely relevant to them.

Thanks for the discussion.  I'll mark this as 'easy' for a first-time contribution.

I am posting this on core-mentorship. If you want to do this, post here and submit the PR within a day.  I will do the merge is no-one else does.

I would be happy to change this. I will submit a PR ASAP.

Hi Terry,

You say we need to keep this illustration with a section 'before 3.6' but in think it's a bad thing.

1. when you read a documentation, you just copy the example, and sometimes you don't read the requirements.
2. why do we need to keep an illustration for a previous version of Python? since >= 3.6 we keep the order (officially in 3.7), in this case, the example is useless, because you read the documentation of >= 3.7.

I would prefer to remove this example for >= 3.6 and keep the illustration for the previous version.

I am really interested by the feedback of Tim, Cheryl and Raymond.

> Raymond, what do you think?

I concur with Tim.

FWIW, set objects are still unordered, so they too require sorting for a reproducible doctest.

Hi Raymond,

Ok, if you agree with Tim, I just created a PR. 

Have a nice day,

Stephane, it's not deep.  People who need to write doctests that work across N versions of Python shouldn't need to read N versions of the documentation.  This is hardly unique to doctest.  We routinely add "Changed in version m.n" blurbs all over the place.

Ways that were _necessary_ for robust dict testing continue to work fine in 3.6 and 3.7, so it doesn't harm anything if people mindlessly copy an example that _could_ be spelled some other way under 3.6+.  It's not like there's even anything slightly obscure about, e.g.,

>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
True

Tim,

I understand. It's just my experience, I have seen a lot of new comers (in my python trainings), they just copy the examples and don't read the total explanation. sometimes, because english is not their native language and in this case, they try to find an example, copy/paste and run it and when there is an exception, they will try to read the doc.

so, I have pushed a PR, I just changed sentences, I am waiting for your suggestions.

Thank you for your explanation.

Hi Raymond and Tim,

I just updated the PR with your recommendations.

Have a nice day,

New changeset 0522fd81dc6e3482c2d4c8719f1f85ad5924eede by Julien Palard (Stéphane Wirtel) in branch 'master':
bpo-34839: Add a 'before 3.6' in the section 'warnings' of doctest (GH-9736)
https://github.com/python/cpython/commit/0522fd81dc6e3482c2d4c8719f1f85ad5924eede

New changeset a910c2c6f3542b61f084de2ece0d8dab09c5a0fa by Miss Islington (bot) in branch '3.7':
bpo-34839: Add a 'before 3.6' in the section 'warnings' of doctest (GH-9736)
https://github.com/python/cpython/commit/a910c2c6f3542b61f084de2ece0d8dab09c5a0fa