I agree that when we land a feature that introduces incompatible change like this, as part of the PR it should also include updating the documentation on how to migrate.
I would think that the feature should not be merged unless the doc has been updated too. 

Perhaps we should include this explicitly in devguide, as one of the things to consider when reviewing pull requests.
Do we have such a guide/doc yet, on how to review CPython pull requests?


On Thu, Jan 21, 2021 at 2:49 AM Victor Stinner <vstinner@python.org> wrote:
Currently, we wait until the first user complains, sometimes after a
3.x.0 final release, before starting to document how to port existing
code. I agree that it should be done earlier.

I suggest that developers who want to introduce an incompatible change
think about how to port existing code, especially if it's possible to
write code compatible with the old and the new behavior. It should be
done while the incompatible change is designed.

I also agree that we document how to port code in the change which
introduce the deprecation, not when we introduce the incompatible
change (ex: remove a function).

I also suggest to communicate on future incompatible changes ;-)

Victor
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/F4YKK4ERIDDYZ7RUVZ5FPJFA4TSA3AP7/
Code of Conduct: http://python.org/psf/codeofconduct/