python · encukou · Sep 20, 2022 · Aug 31, 2022 · Aug 31, 2022 · Aug 31, 2022
diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst
@@ -27,14 +27,15 @@ Gaining Commit Privileges
 
 The steps to gaining commit privileges are:
 
-1. A core developer starts a poll at https://discuss.python.org/c/committers/5
+1. A core developer starts a poll in the
+   `Committers category`_ on the `Python Discourse`_ (``discuss.python.org``)
 
    - Open for 7 days
    - Results shown upon close
 
-2. The poll is announced on python-committers
+2. The poll is announced on the `python-committers mailing list`_
 3. Wait for the poll to close and see if the results confirm your membership
-   as per the voting results required by PEP 13
+   as per the voting results required by :pep:`13`
 4. The person who nominated you emails the steering council with your email
    address and a request that the council either accept or reject the proposed
    membership
@@ -44,7 +45,7 @@ The steps to gaining commit privileges are:
    - Account details as required by
      🔒 https://github.com/python/voters/
    - Your preferred email address to
-     subscribe to python-committers with
+     subscribe to the python-committers mailing list with
    - A reminder about the `Code of Conduct`_ and to report issues to the PSF
      Conduct WG
 
@@ -54,6 +55,9 @@ The steps to gaining commit privileges are:
 8. They will update the devguide to publicly list your team membership at
    :ref:`developers`
 9. An announcement email by the steering council member handling your new
-   membership will be sent to python-committers
+   membership will be sent to the Committers Discourse category
 
 .. _Code of Conduct: https://www.python.org/psf/conduct/
+.. _Committers category: https://discuss.python.org/c/committers/5
+.. _Python Discourse: https://discuss.python.org
+.. _python-committers mailing list: https://mail.python.org/mailman3/lists/python-committers.python.org/
diff --git a/core-developers/committing.rst b/core-developers/committing.rst
@@ -39,7 +39,9 @@ to enter the public source tree. Ask yourself the following questions:
    :ref:`Run the entire test suite <runtests>` to make sure that everything
    still passes. If there is a change to the semantics, then there needs to
    be a strong reason, because it will cause some peoples' code to break.
-   If you are unsure if the breakage is worth it, then ask on python-dev.
+   If you are unsure if the breakage is worth it, then ask
+   on the `Core Development Discourse category
+   <https://discuss.python.org/c/core-dev/23>`__.
 
 * **Does documentation need to be updated?**
    If the pull request introduces backwards-incompatible changes (e.g.

diff --git a/core-developers/experts.rst b/core-developers/experts.rst
@@ -9,9 +9,11 @@ Interest Areas and GitHub names for each item that indicate a maintainer or
 an expert in the field.  This list is intended to be used by issue submitters,
 issue triage people, and other issue participants to find people to @mention
 or add as reviewers to issues and pull requests.  People on this list may be
-asked to render final judgement on a feature or bug.  If no active maintainer
-is listed for a given module, then questionable changes should go to
-python-dev, while any other issues can and should be decided by any committer.
+asked to render final judgment on a feature or bug.  If no active maintainer
+is listed for a given module, then questionable changes should be discussed
+on the `Core Development Discourse category
+<https://discuss.python.org/c/core-dev/23>`__,
+while any other issues can and should be decided by any committer.
 
 Developers can choose to follow labels, so if a label that they are
 following is added to an issue or pull request, they will be notified

diff --git a/core-developers/motivations.rst b/core-developers/motivations.rst
@@ -88,9 +88,11 @@ participating in the CPython core development process:
 
    If there's a kind of link you'd like to include in your entry that isn't
    already covered by the categories mentioned above, please start a discussion
-   about that on the python-committers mailing list.
+   about that on the Committers category on the Python Discourse
+   (discuss.python.org) or the python-committers mailing list.
 
-   python-committers is also the appropriate point of contact for any other
+   The Committers Discourse category or the python-committers mailing list
+   is also the appropriate point of contact for any other
    questions or suggestions relating to this page.
 
 .. topic:: Brett Cannon (Canada)

diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst
@@ -9,7 +9,8 @@ collaborate constructively with other contributors, including core developers.
 This responsibility covers all forms of contribution, whether that's submitting
 patches to the implementation or documentation, reviewing other peoples'
 patches, triaging issues on the issue tracker, or discussing design and
-development ideas on the core mailing lists.
+development ideas on the core
+:ref:`communication channels <communication-channels>`.
 
 Core developers accept key additional responsibilities around the ongoing
 management of the project:
@@ -23,29 +24,33 @@ management of the project:
   with this part of the process, and it is most welcome when they do, the
   actual responsibility rests with the core developer that merged the change
 * core developers also bear the primary responsibility for deciding when
-  changes proposed on the issue tracker should be escalated to python-ideas
-  or python-dev for wider discussion, as well as suggesting the use of the
+  changes proposed on the issue tracker should be escalated to
+  the appropriate :ref:`Discourse <communication-discourse>` category
+  for wider discussion, as well as suggesting the use of the
   Python Enhancement Proposal process to manage the design and justification
   of complex changes, or changes with a potentially significant impact on
   end users
 
 As a result of the additional responsibilities they accept, core developers
 gain the privilege of being able to approve proposed changes, as well as being
 able to reject them as inappropriate. Core developers are also able to request
-that even already merged changes be escalated to python-dev for further
-discussion, and potentially even reverted prior to release.
+that even already merged changes be escalated to
+:ref:`Discourse <communication-discourse>` for further discussion,
+and potentially even reverted prior to release.
 
 Becoming a core developer isn't a binary "all-or-nothing" status - CPython
 is a large project, and different core developers accept responsibility for
 making design and development decisions in different areas (as documented
 in the :ref:`experts` and :ref:`developers`).
 
 
-Mailing Lists and Bug Notifications
-===================================
+Communication Channels and Bug Notifications
+============================================
 
-Mailing lists have generally been replaced by the `Discourse forum
-<https://discuss.python.org/>`_. Refer to :ref:`mailinglists` for more information.
+Mailing lists have generally been replaced by the
+`Discourse forum <https://discuss.python.org/>`_ (``discuss.python.org``).
+Refer to the :ref:`mailinglists` and :ref:`communication-discourse` sections
+for more information.
 
 If you want notification of new issues, you can use the appropriate GitHub notification
 settings for the `python/cpython <https://github.com/python/cpython>`_ repository —

diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst
@@ -5,8 +5,8 @@
 Following Python's Development
 ==============================
 
-Python's development is communicated through a myriad of ways, mostly through
-mailing lists, but also other forms.
+Python's development is communicated through a myriad of ways,
+primarily :ref:`Discourse <communication-discourse>` along with other platforms.
 
 
 Standards of behaviour in these communication channels
@@ -63,9 +63,6 @@ be mirrored at `GMANE <https://gmane.io/>`_ and can be read and posted to in var
 ways, including via web browsers, NNTP newsreaders, and RSS feed readers.
 
 .. _issue tracker: https://github.com/python/cpython/issues
-.. _new-bugs-announce: https://mail.python.org/mailman/listinfo/new-bugs-announce
-.. _python-bugs-list: https://mail.python.org/mailman/listinfo/python-bugs-list
-.. _python-checkins: https://mail.python.org/mailman/listinfo/python-checkins
 .. _python-committers: https://mail.python.org/mailman3/lists/python-committers.python.org/
 .. _python-dev: https://mail.python.org/mailman3/lists/python-dev.python.org/
 .. _python-help: https://mail.python.org/mailman/listinfo/python-help
@@ -77,7 +74,7 @@ ways, including via web browsers, NNTP newsreaders, and RSS feed readers.
 .. _web gateway: https://mail.python.org/archives/
 
 
-.. _discourse_discuss:
+.. _communication-discourse:
 
 Discourse (discuss.python.org web forum)
 ========================================
@@ -94,8 +91,8 @@ the `Committers`_ category, where posting is restricted to the `CPython
 <https://github.com/python/cpython>`_ core developers.
 
 The Committers category is often used for announcements and notifications.
-It is also a common venue for the core developer promotion votes (this
-category is equivalent to the python-committers mailing list).
+It is also the designated venue for the core developer promotion votes
+(as the Discourse equivalent of the `python-committers`_ mailing list).
 
 Tutorials for new users
 -------------------------
@@ -187,6 +184,7 @@ mailing list mode" and save changes.
 .. _Ideas: https://discuss.python.org/c/ideas/6
 .. _Python Help: https://discuss.python.org/c/users/7
 
+
 Discord (private chat server)
 =============================
 
@@ -224,7 +222,6 @@ set a specific `Server Nickname`_
 .. _Server Nickname: https://support.discord.com/hc/en-us/articles/219070107-Server-Nicknames
 
 
-
 IRC
 ===
 

diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst
@@ -23,7 +23,7 @@ Because of the seriousness that language changes carry, any change must be
 beneficial to a large proportion of Python users. If the change only benefits a
 small percentage of Python developers then the change will not be made. A good
 way to see if your idea would work for a large portion of the Python community
-is to ask on :ref:`python-list or python-ideas <communication>`. You can also
+is to ask in the `Ideas Discourse category`_. You can also
 go through Python's stdlib and find examples of code which would benefit from
 your proposed change (which helps communicate the usefulness of your change to
 others). For further guidance, see :ref:`suggesting-changes`.
@@ -33,34 +33,6 @@ Council can truly classify something as Pythonic, you can read the
 :pep:`Zen of Python <20>` for guidance.
 
 
-.. index:: PEP process
-
-PEP Process
------------
-Once you are certain you have a language change proposal which will appeal to
-the general Python community, you can begin the process of officially proposing
-the change. This process is the Python Enhancement Proposal (PEP) process.
-:PEP:`1` describes it in detail.
-
-You will first need a PEP that you will present to python-ideas. You may be a
-little hazy on the technical details as various core developers can help with
-that, but do realize that if you do not present your idea to python-ideas or
-python-list ahead of time you may find out it is technically not possible.
-Expect extensive comments on the PEP, some of which will be negative.
-
-Once your PEP has been modified to be of proper quality and to take into
-account comments made on python-ideas, it may proceed to python-dev. There it
-will be assigned a PEP dictator and another general discussion will occur. Once
-again, you will need to modify your PEP to incorporate the large amount of
-comments you will receive.
-
-The PEP dictator decides if your PEP is accepted (typically based on whether
-most core developers support the PEP). If that occurs then your proposed
-language change will be introduced in the next release of Python. Otherwise
-your PEP will be recorded as rejected along with an explanation as to why so
-that others do not propose the same language change in the future.
-
-
 .. index::
    single: PEP process
 
@@ -69,27 +41,49 @@ that others do not propose the same language change in the future.
 Suggesting new features and language changes
 --------------------------------------------
 
-The `python-ideas`_ mailing list is specifically intended for discussion of
-new features and language changes. Please don't be disappointed if your
-idea isn't met with universal approval: as the long list of Rejected and
-Withdrawn PEPs in the `PEP Index`_ attests, and as befits a reasonably mature
-programming language, getting significant changes into Python isn't a simple
-task.
+The `Ideas Discourse category`_
+is specifically intended for discussion of new features and language changes.
+Please don't be disappointed if your idea isn't met with universal approval:
+as the :pep:`long list of Withdrawn and Rejected PEPs
+<0#abandoned-withdrawn-and-rejected-peps>`
+in the :pep:`PEP Index <0>` attests,
+and as befits a reasonably mature programming language,
+getting significant changes into Python isn't a simple task.
 
 If the idea is reasonable, someone will suggest posting it as a feature
-request on the `issue tracker`_, or, for larger changes, writing it up as
-a :pep:`draft PEP <1>`.
+request on the `issue tracker`_, or, for larger changes,
+writing it up as PEP following the :ref:`lang-changes-pep-process`.
+
+Sometimes core developers will differ in opinion,
+or merely be collectively unconvinced.
+When there isn't an obvious victor, then the `Status Quo Wins a Stalemate`_.
 
-Sometimes core developers will differ in opinion, or merely be collectively
-unconvinced. When there isn't an obvious victor then the
-`Status Quo Wins a Stalemate`_ as outlined in the linked post.
+For some examples on language changes that were accepted,
+see `Justifying Python Language Changes`_.
+
+
+.. index:: PEP process
+
+.. _lang-changes-pep-process:
+
+PEP Process
+-----------
+
+Once you are certain you have a language change proposal
+which will appeal to the general Python community,
+you can begin the :abbr:`PEP (Python enhancement proposal)` process
+to officially propose the change.
+See :pep:`1` for information on PEPs and the PEP process,
+and the :pep:`PEP Index <0>` for examples.
+
+If the PEP is accepted, then your proposed language change will be introduced
+in the next release of Python.
+Otherwise, your PEP will be recorded as rejected along with an explanation,
+to inform others who may propose a similar language change in the future.
 
-For some examples on language changes that were accepted please read
-`Justifying Python Language Changes`_.
 
-.. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org/
 .. _issue tracker: https://github.com/python/cpython/issues
-.. _PEP Index: https://peps.python.org/
-.. _draft PEP: https://www.python.org/dev/peps/pep-0001/
+.. _Ideas Discourse category: https://discuss.python.org/c/ideas/6
 .. _Status Quo Wins a Stalemate: https://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html
 .. _Justifying Python Language Changes: https://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html
+
diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst
@@ -20,19 +20,19 @@ If you have found that a function, method, or class is useful and you believe
 it would be useful to the general Python community, there are some steps to go
 through in order to see it added to the stdlib.
 
-First is you should gauge the usefulness of the code. Typically this is done
-by sharing the code publicly. You have a couple of options for this. One is to
-post it online at the `Python Cookbook`_. Based on feedback or reviews of the
-recipe you can see if others find the functionality as useful as you do.
-A search of the issue tracker for previous suggestions related to the proposed
-addition may turn up a rejected issue that explains why the suggestion will not
-be accepted.
-Another is to do a blog post about the code and see what kind of responses you
-receive. Posting to python-list (see :ref:`communication` for where to find the
-list and other mailing lists) to discuss your code also works. Finally, asking
-on a specific :abbr:`SIG (special interest group)` from mail.python.org or
-python-ideas is also acceptable. This is not a required step but it is
-suggested.
+First, you should gauge the usefulness of the code,
+which is typically done by sharing the code publicly.
+This is not a required step, but it is suggested.
+You have a several options for this:
+
+* Search the `issue tracker`_ for discussion related to the proposed addition.
+  This may turn up an issue that explains why the suggestion wasn't accepted.
+* Open a new thread in the `Ideas Discourse category`_
+  to gather feedback directly from the Python core developers and community.
+* Write a blog post about the code, which may also help gather useful feedback.
+* Post it to the `Python Cookbook`_.
+  Based on feedback and reviews of the recipe,
+  you can see if others find the functionality as useful as you do.
 
 If you have found general acceptance and usefulness for your code from people,
 you can open an issue on the `issue tracker`_ with the code attached as a
@@ -46,6 +46,7 @@ Through your public sharing of your code in order to gauge community support
 for it you at least can know that others will come across it who may find it
 useful.
 
+.. _Ideas Discourse category: https://discuss.python.org/c/ideas/6
 .. _Python Cookbook: https://code.activestate.com/recipes/langs/python/
 
 
@@ -121,30 +122,16 @@ uniform.
 
 Proposal Process
 ''''''''''''''''
-If the module you want to propose adding to the stdlib meets the proper
-requirements, you may propose its inclusion. To start, you should email
-python-list or python-ideas to make sure the community in general would support
-the inclusion of the module (see :ref:`communication`).
-
-If the feedback from the community is positive overall, you will need to write
-a :abbr:`PEP (Python enhancement proposal)` for the module's inclusion. It
-should outline what the module's overall goal is, why it should be included in
-the stdlib, and specify the API of the module. See the `PEP index`_ for PEPs
-that have been accepted before that proposed a module for inclusion.
-
-Once your PEP is written, send it to python-ideas for basic vetting. Be
-prepared for extensive feedback and lots of discussion (not all of it
-positive). This will help make the PEP be of good quality and properly
-formatted.
-
-When you have listened to, responded, and integrated as appropriate the
-feedback from python-ideas into your PEP, you may send it to python-dev. You
-will once again receive a large amount of feedback and discussion. A PEP
-dictator will be assigned who makes the final call on whether the PEP will be
-accepted or not. If the PEP dictator agrees to accept your PEP (which typically
-means that the core developers end up agreeing in general to accepting
-your PEP) then the module will be added to the stdlib once the creators of the
-module sign :ref:`contributor agreements <contributor_agreement>`.
+
+If the module you want to propose adding to the stdlib meets the requirements,
+you may propose its inclusion
+by following the :abbr:`PEP (Python Enhancement Proposal)` process.
+See :pep:`1` for details,
+and the :pep:`PEP index <0>` for previously-accepted PEPs
+that have proposed a module for inclusion.
+
+If the PEP is accepted, then the module will be added to the stdlib
+once the authors of the module sign
+:ref:`contributor agreements <contributor_agreement>`.
 
 .. _issue tracker: https://github.com/python/cpython/issues
-.. _PEP index: https://peps.python.org/