From 046bd6948cbc151e75cab2d710562f5af9e356ed Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 30 Aug 2022 21:03:32 -0500 Subject: [PATCH 1/8] Revise PEP sections to reduce duplication, & point to PEP 1 & Discourse --- developer-workflow/lang-changes.rst | 85 ++++++++++++++--------------- developer-workflow/stdlib.rst | 64 +++++++++------------- 2 files changed, 66 insertions(+), 83 deletions(-) diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst index 108b7b334..90bee5520 100644 --- 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 `. You can also +is to ask in the `Ideas category`_ on the `Python Discourse`_. 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,50 @@ 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 category`_ on the `Python Discourse`_ +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/ .. _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 + +.. _Python Discourse: https://discuss.python.org/ +.. _Ideas category: https://discuss.python.org/c/ideas/6 diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 208629bd4..58b113c68 100644 --- 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 category`_ on the `Python Discourse`_ + 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,8 @@ 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. +.. _Python Discourse: https://discuss.python.org/ +.. _Ideas category: https://discuss.python.org/c/ideas/6 .. _Python Cookbook: https://code.activestate.com/recipes/langs/python/ @@ -121,30 +123,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 `. + +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 `. .. _issue tracker: https://github.com/python/cpython/issues -.. _PEP index: https://peps.python.org/ From a707c0bdd0385c1177a359aad9f212109d6e9d12 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 30 Aug 2022 22:36:47 -0500 Subject: [PATCH 2/8] Update places that require/recommend the mailing lists to Discourse --- core-developers/committing.rst | 3 ++- core-developers/experts.rst | 7 +++--- core-developers/responsibilities.rst | 13 +++++++---- developer-workflow/communication-channels.rst | 4 ++-- getting-started/getting-help.rst | 23 +++++++++++-------- getting-started/pull-request-lifecycle.rst | 9 +++++--- triage/issue-tracker.rst | 15 ++++-------- triage/labels.rst | 6 ++--- 8 files changed, 44 insertions(+), 36 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index d4832ebbd..af6aa5912 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -39,7 +39,8 @@ to enter the public source tree. Ask yourself the following questions: :ref:`Run the entire test suite ` 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 Discourse `__. * **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 index c33004bf7..b58e72eae 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -9,9 +9,10 @@ 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 Discourse `__, +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/responsibilities.rst b/core-developers/responsibilities.rst index f3e3341f9..3d4f936b0 100644 --- 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 `. Core developers accept key additional responsibilities around the ongoing management of the project: @@ -23,8 +24,9 @@ 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 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 @@ -32,8 +34,9 @@ management of the project: 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 ` 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 diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index ecf42fec1..532de3a9f 100644 --- 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 ` along with other platforms. Standards of behaviour in these communication channels diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index 60284d955..f40bfdf77 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -13,6 +13,9 @@ Should you require help, there are a :ref:`variety of options available usage then please check the rest of this guide first as it should answer your question. + +.. _help-discourse: + Discourse --------- @@ -35,18 +38,20 @@ categories, such as Mailing Lists ------------- -Further options for seeking assistance include the `python-ideas`_ and -`python-dev`_ mailing lists. Python-ideas contains discussion of speculative -Python language ideas for possible inclusion into the language. If an idea -gains traction it can then be discussed and honed to the point of becoming a -solid proposal and presented on python-dev. Python-dev contains discussion -of current Python design issues, release mechanics, and maintenance of -existing releases. These mailing lists are for questions involving the +Further options for seeking assistance include the +`python-ideas`_ and `python-dev`_ mailing lists, +which respectively correspond to the Ideas and Core Development +:ref:`help-discourse` categories, respectively. +The Discourse categories are generally more active +and are the preferred venue for new discussions, +but the mailing lists are still monitored and responded to. +These mailing lists are for questions involving the development *of* Python, **not** for development *with* Python. .. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org .. _python-dev: https://mail.python.org/mailman3/lists/python-dev.python.org/ + Ask #python-dev --------------- @@ -74,8 +79,8 @@ an office hour, before posting to python-dev mailing list or filing bugs. .. warning:: - This is no longer actively monitored by core devs. Consider asking your questions - on Discourse or on the `python-dev`_ mailing list. + This is no longer actively monitored by core devs. + Consider asking your questions in the relevant `Discourse`_ category instead. .. _Zulip: https://python.zulipchat.com diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 5f2a4262d..4bf5eead7 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -397,9 +397,10 @@ request (we cannot force anyone to review pull requests and no one is employed to look at pull requests). If your pull request has not received any notice from reviewers (i.e., no comment made) after one month, first "ping" the issue on the `issue tracker`_ to remind the -nosy list that the pull request needs a review. If you don't get a response -within a week after pinging the issue, then you can try emailing -python-dev@python.org to ask for someone to review your pull request. +nosy list that the pull request needs a review. +If you don't get a response within a week after pinging the issue, +you can post on the `Core Development category`_ of the `Python Discourse`_ +to ask for someone to review your pull request. When someone does manage to find the time to look at your pull request they will most likely make comments about how it can be improved @@ -502,3 +503,5 @@ asked to make these edits on the behalf of the core developer who accepts your pull request. .. _issue tracker: https://github.com/python/cpython/issues +.. _Python Discourse: https://discuss.python.org/ +.. _Core Development category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 6a0ae22d6..b95ab2b88 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -107,7 +107,8 @@ with the resolution of the issue. On reflection, the resolution steps may seem more reasonable than you initially thought. If you still feel the resolution is incorrect, then raise a thoughtful question -on `python-dev`_. Further argument and disrespectful discourse on `python-dev`_ +on the `Core Development category`_ of the `Python Discourse`_. +Further argument and disrespectful responses after a consensus has been reached amongst the core developers is unlikely to win any converts. @@ -117,19 +118,13 @@ reason either as ``complete`` or ``not planned``. .. seealso:: - `The Python issue tracker `_ + `The Python issue tracker `_ Where to report issues about Python. - `The New-bugs-announce mailing list `_ - Where all the new issues created on the tracker are reported. - - `The Python-bugs-list mailing list `_ - Where all the changes to issues are reported. - .. _issue tracker: https://github.com/python/cpython/issues .. _advanced search: https://github.com/search/advanced .. _devguide repo: https://github.com/python/devguide/issues .. _Roundup: https://roundup.sourceforge.io/ -.. _Discourse: https://discuss.python.org/ -.. _python-dev: https://mail.python.org/mailman/listinfo/python-dev +.. _Python Discourse: https://discuss.python.org/ +.. _Core Development category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/labels.rst b/triage/labels.rst index 78a5ac9b5..acbc73358 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -220,8 +220,8 @@ specific type, please do not set a type. | | arguments for existing functions. Also used for | | | improvements in the documentation, test suite and | | | other refactorings. A good place to discuss enhancements | -| | prior to filing an issue is `python-ideas`_ mailing | -| | list. | +| | prior to filing an issue is `Ideas category`_ | +| | on the :ref:`Python Discourse `. | +----------------+----------------------------------------------------------+ | performance | Situations where too much time is necessary to complete | | | the task. For example, a common task now takes | @@ -410,4 +410,4 @@ a link to relevant web pages. .. _Parser: https://github.com/python/cpython/tree/main/Parser/ .. _Python: https://github.com/python/cpython/tree/main/Python/ .. _Reporting security issues in Python: https://www.python.org/dev/security/ -.. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org +.. _Ideas category: https://discuss.python.org/c/ideas/6 From 95b2ff2280dd2e14b47b75063754fffc31deda08 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 30 Aug 2022 22:40:43 -0500 Subject: [PATCH 3/8] Clarify and update existing references to Discourse --- core-developers/responsibilities.rst | 10 ++++++---- developer-workflow/communication-channels.rst | 5 +---- triage/issue-tracker.rst | 7 ++++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst index 3d4f936b0..ff97b2820 100644 --- a/core-developers/responsibilities.rst +++ b/core-developers/responsibilities.rst @@ -44,11 +44,13 @@ 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 -`_. Refer to :ref:`mailinglists` for more information. +Mailing lists have generally been replaced by the +`Discourse forum `_ (``discuss.python.org``). +Refer to the :ref:`mailinglists` and :ref:`discourse_discuss` sections +for more information. If you want notification of new issues, you can use the appropriate GitHub notification settings for the `python/cpython `_ repository — diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 532de3a9f..0033b5a98 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -63,9 +63,6 @@ be mirrored at `GMANE `_ 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 @@ -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/triage/issue-tracker.rst b/triage/issue-tracker.rst index b95ab2b88..2afeb0aee 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -67,9 +67,10 @@ available choices are: possible changes to future Python versions, track core development discussions, or join a specific special-interest group. -Depending on your choice, a dedicated form template will appear. In particular, -you'll notice that the last button actually takes you to `Discourse`_ where -many Python-related discussions take place. +Depending on your choice, a dedicated form template will appear. +In particular, you'll notice that the last button actually takes you to +the `Python Discourse`_ (``discuss.python.org``), +where many Python-related discussions take place. The submission form has only two fields that you need to fill: From ee35ee778e2d821714ea210c15a314f17d00bed1 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 30 Aug 2022 22:41:32 -0500 Subject: [PATCH 4/8] Focus Discourse material in Getting Help on getting help with core dev --- getting-started/getting-help.rst | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index f40bfdf77..c12bf4bf8 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -19,21 +19,29 @@ question. Discourse --------- -Python has a hosted :ref:`Discourse ` instance. This forum has many different -categories and most core development discussions take place in the open forum -categories for `PEPs`_ and `Core Development`_ . -Most categories are open for all users to read and post with the exception of -Committers and Core Development categories. Be sure to visit the related Core -categories, such as -`Core Development `_ and -`Core Workflow `_. +Python has a hosted Discourse instance at `discuss.python.org `_. +This forum has many different categories, +of which all but `Committers`_ are open for all users to read and post. +For most general questions and help related to the development +of the Python language, interpreter and standard library itself +(as opposed to developing your own libraries and applications *with* Python), +the `Core Development category`_ is the place to ask. +The `Ideas category`_ is the place to propose and discuss new ideas +for the Python language and standard library, +while the `Core Workflow category`_ is the place to post +about questions, concerns and issues with the dev infrastructure and bots. .. seealso:: - :ref:`Discourse ` - on how to get started. + :ref:`discourse_discuss` for more information on how to get started. +.. _Discourse: https://discuss.python.org/ +.. _Committers: https://discuss.python.org/c/committers/5 +.. _Core Development category: https://discuss.python.org/c/core-dev/23 +.. _Core Workflow category: https://discuss.python.org/c/core-workflow/8 +.. _Ideas category: https://discuss.python.org/c/ideas/6 -.. _PEPs: https://discuss.python.org/c/peps/ + +.. _help-mailing-lists: Mailing Lists ------------- From 882114893ef67b1efb9c3862af82d3efc5c02547 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 1 Sep 2022 19:13:27 -0500 Subject: [PATCH 5/8] Update mentions of Python-Committers mailing list to mention Discourse --- core-developers/become-core-developer.rst | 14 +++++++++----- core-developers/motivations.rst | 6 ++++-- developer-workflow/communication-channels.rst | 4 ++-- triage/triage-team.rst | 8 +++++--- 4 files changed, 20 insertions(+), 12 deletions(-) diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index 3c352c037..1c8ef74e7 100644 --- 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/motivations.rst b/core-developers/motivations.rst index 41e3156ec..1c813730d 100644 --- 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/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 0033b5a98..df016c1d0 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -91,8 +91,8 @@ the `Committers`_ category, where posting is restricted to the `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 ------------------------- diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 36994cd72..6bd530c05 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -95,6 +95,8 @@ tracker, they will ask a :ref:`Python organization admin ` to invite you to the Python organisation, and then act as a mentor to you until you are ready to do things entirely on your own. -For every new triager, it would be great to announce them in the python-committers -mailing list and core-workflow category in Discourse. `Example announcement -`_. +For every new triager, it would be great to announce them in the +`Committers category `_ +on the `Python Discourse `_ +(`example announcement +`__). From 55826b1f74bb52b653caf45bed30257d6080bac7 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 1 Sep 2022 20:11:02 -0500 Subject: [PATCH 6/8] Elide not so useful seperate Discourse link from category mentions --- core-developers/committing.rst | 3 ++- core-developers/experts.rst | 3 ++- developer-workflow/lang-changes.rst | 7 +++---- developer-workflow/stdlib.rst | 5 ++--- getting-started/getting-help.rst | 3 ++- getting-started/pull-request-lifecycle.rst | 5 ++--- triage/issue-tracker.rst | 4 ++-- triage/labels.rst | 6 +++--- 8 files changed, 18 insertions(+), 18 deletions(-) diff --git a/core-developers/committing.rst b/core-developers/committing.rst index af6aa5912..29cff328e 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -40,7 +40,8 @@ to enter the public source tree. Ask yourself the following questions: 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 Discourse `__. + on the `Core Development Discourse category + `__. * **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 index b58e72eae..273fce5b4 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -11,7 +11,8 @@ 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 judgment on a feature or bug. If no active maintainer is listed for a given module, then questionable changes should be discussed -`on Discourse `__, +on the `Core Development Discourse category +`__, 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 diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst index 90bee5520..7d663530c 100644 --- 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 in the `Ideas category`_ on the `Python Discourse`_. 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`. @@ -41,7 +41,7 @@ Council can truly classify something as Pythonic, you can read the Suggesting new features and language changes -------------------------------------------- -The `Ideas category`_ on the `Python Discourse`_ +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 @@ -83,8 +83,7 @@ to inform others who may propose a similar language change in the future. .. _issue tracker: https://github.com/python/cpython/issues +.. _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 -.. _Python Discourse: https://discuss.python.org/ -.. _Ideas category: https://discuss.python.org/c/ideas/6 diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 58b113c68..22b9a7f36 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -27,7 +27,7 @@ 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 category`_ on the `Python Discourse`_ +* 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`_. @@ -46,8 +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. -.. _Python Discourse: https://discuss.python.org/ -.. _Ideas category: https://discuss.python.org/c/ideas/6 +.. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 .. _Python Cookbook: https://code.activestate.com/recipes/langs/python/ diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index c12bf4bf8..ac6b6daa5 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -88,7 +88,8 @@ an office hour, before posting to python-dev mailing list or filing bugs. .. warning:: This is no longer actively monitored by core devs. - Consider asking your questions in the relevant `Discourse`_ category instead. + Consider asking your questions in the relevant + :ref:`Discourse ` category instead. .. _Zulip: https://python.zulipchat.com diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 4bf5eead7..907e6783a 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -399,7 +399,7 @@ received any notice from reviewers (i.e., no comment made) after one month, first "ping" the issue on the `issue tracker`_ to remind the nosy list that the pull request needs a review. If you don't get a response within a week after pinging the issue, -you can post on the `Core Development category`_ of the `Python Discourse`_ +you can post on the `Core Development Discourse category`_ to ask for someone to review your pull request. When someone does manage to find the time to look at your pull request @@ -503,5 +503,4 @@ asked to make these edits on the behalf of the core developer who accepts your pull request. .. _issue tracker: https://github.com/python/cpython/issues -.. _Python Discourse: https://discuss.python.org/ -.. _Core Development category: https://discuss.python.org/c/core-dev/23 +.. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 2afeb0aee..976cf1891 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -108,7 +108,7 @@ with the resolution of the issue. On reflection, the resolution steps may seem more reasonable than you initially thought. If you still feel the resolution is incorrect, then raise a thoughtful question -on the `Core Development category`_ of the `Python Discourse`_. +on the `Core Development Discourse category`_. Further argument and disrespectful responses after a consensus has been reached amongst the core developers is unlikely to win any converts. @@ -128,4 +128,4 @@ reason either as ``complete`` or ``not planned``. .. _devguide repo: https://github.com/python/devguide/issues .. _Roundup: https://roundup.sourceforge.io/ .. _Python Discourse: https://discuss.python.org/ -.. _Core Development category: https://discuss.python.org/c/core-dev/23 +.. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/labels.rst b/triage/labels.rst index acbc73358..341dc6675 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -220,8 +220,8 @@ specific type, please do not set a type. | | arguments for existing functions. Also used for | | | improvements in the documentation, test suite and | | | other refactorings. A good place to discuss enhancements | -| | prior to filing an issue is `Ideas category`_ | -| | on the :ref:`Python Discourse `. | +| | prior to filing an issue is the | +| | `Ideas Discourse category`_. | +----------------+----------------------------------------------------------+ | performance | Situations where too much time is necessary to complete | | | the task. For example, a common task now takes | @@ -410,4 +410,4 @@ a link to relevant web pages. .. _Parser: https://github.com/python/cpython/tree/main/Parser/ .. _Python: https://github.com/python/cpython/tree/main/Python/ .. _Reporting security issues in Python: https://www.python.org/dev/security/ -.. _Ideas category: https://discuss.python.org/c/ideas/6 +.. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 From f074c0cfd08ef4beace01c25af281c9229efa161 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 1 Sep 2022 20:38:09 -0500 Subject: [PATCH 7/8] Update ref target label for Discourse comm channels section --- core-developers/responsibilities.rst | 6 +++--- developer-workflow/communication-channels.rst | 4 ++-- getting-started/getting-help.rst | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst index ff97b2820..aec4b98cc 100644 --- a/core-developers/responsibilities.rst +++ b/core-developers/responsibilities.rst @@ -25,7 +25,7 @@ management of the project: 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 - the appropriate :ref:`Discourse category ` + the appropriate :ref:`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 @@ -35,7 +35,7 @@ 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 -:ref:`Discourse ` for further discussion, +:ref:`Discourse ` for further discussion, and potentially even reverted prior to release. Becoming a core developer isn't a binary "all-or-nothing" status - CPython @@ -49,7 +49,7 @@ Communication Channels and Bug Notifications Mailing lists have generally been replaced by the `Discourse forum `_ (``discuss.python.org``). -Refer to the :ref:`mailinglists` and :ref:`discourse_discuss` sections +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 diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index df016c1d0..239855bb1 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -6,7 +6,7 @@ Following Python's Development ============================== Python's development is communicated through a myriad of ways, -primarily :ref:`Discourse ` along with other platforms. +primarily :ref:`Discourse ` along with other platforms. Standards of behaviour in these communication channels @@ -74,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) ======================================== diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index ac6b6daa5..361a53258 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -32,7 +32,7 @@ while the `Core Workflow category`_ is the place to post about questions, concerns and issues with the dev infrastructure and bots. .. seealso:: - :ref:`discourse_discuss` for more information on how to get started. + :ref:`communication-discourse` for more information on how to get started. .. _Discourse: https://discuss.python.org/ .. _Committers: https://discuss.python.org/c/committers/5 @@ -89,7 +89,7 @@ an office hour, before posting to python-dev mailing list or filing bugs. This is no longer actively monitored by core devs. Consider asking your questions in the relevant - :ref:`Discourse ` category instead. + :ref:`Discourse ` category instead. .. _Zulip: https://python.zulipchat.com From 23a17be9e9f17cebc888df2503f1235cbbe80306 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 1 Sep 2022 22:01:00 -0500 Subject: [PATCH 8/8] Implement further reviewer suggestions and feedback --- developer-workflow/stdlib.rst | 2 +- getting-started/getting-help.rst | 24 ++++++++++-------------- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 22b9a7f36..176c72679 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -125,7 +125,7 @@ Proposal Process 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. +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. diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index 361a53258..456403a10 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -21,24 +21,20 @@ Discourse Python has a hosted Discourse instance at `discuss.python.org `_. This forum has many different categories, -of which all but `Committers`_ are open for all users to read and post. -For most general questions and help related to the development -of the Python language, interpreter and standard library itself -(as opposed to developing your own libraries and applications *with* Python), -the `Core Development category`_ is the place to ask. -The `Ideas category`_ is the place to propose and discuss new ideas -for the Python language and standard library, -while the `Core Workflow category`_ is the place to post -about questions, concerns and issues with the dev infrastructure and bots. +most of which are open for all users to read and post. +Those particularly relevant for help contributing to Python itself include: + +* `Core Development`_ for most general questions and help +* `Ideas`_ to discuss new ideas for the Python +* `Core Workflow`_ for questions about the dev infrastructure and bots .. seealso:: :ref:`communication-discourse` for more information on how to get started. .. _Discourse: https://discuss.python.org/ -.. _Committers: https://discuss.python.org/c/committers/5 -.. _Core Development category: https://discuss.python.org/c/core-dev/23 -.. _Core Workflow category: https://discuss.python.org/c/core-workflow/8 -.. _Ideas category: https://discuss.python.org/c/ideas/6 +.. _Core Development: https://discuss.python.org/c/core-dev/23 +.. _Core Workflow: https://discuss.python.org/c/core-workflow/8 +.. _Ideas: https://discuss.python.org/c/ideas/6 .. _help-mailing-lists: @@ -48,7 +44,7 @@ Mailing Lists Further options for seeking assistance include the `python-ideas`_ and `python-dev`_ mailing lists, -which respectively correspond to the Ideas and Core Development +which correspond to the `Ideas`_ and `Core Development`_ :ref:`help-discourse` categories, respectively. The Discourse categories are generally more active and are the preferred venue for new discussions,