communication-channels.rst

.. _communication-channels:
.. _communication:

==============================
Following Python's development
==============================

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
======================================================

We try to foster environments of mutual respect, tolerance and encouragement,
as described in the PSF's `Diversity Statement`_. Abiding by the guidelines
in this document and asking questions or posting suggestions in the
appropriate channels are an excellent way to get started on the mutual respect
part, greatly increasing the chances of receiving tolerance and encouragement
in return.

.. _Diversity Statement: https://www.python.org/psf/diversity/


.. _multicultural-communication:

Communicating across cultures and languages
===========================================

Not every contributor writes English as a first language, and phrasing that
feels neutral in one culture can read as blunt or rude in another.

**Practice active listening.** Try to focus on understanding the message before reacting.

**Confirm understanding.** Ask open-ended questions and paraphrase to avoid
misunderstandings. If you're unsure what someone meant, ask: "I want to make
sure I understand: are you saying X?"

**Use translation tools freely.** If English isn't your first language,
translation software or AI tools may help you check that your message has the
tone you intend. Getting the phrasing wrong can make a reasonable point sound
more aggressive than it is.

**Watch out for rhetorical questions.** They read as hostile in text even when
that's not the intent at all:

* Instead of "Why do you think it is wrong?!", try "That doesn't sound right
  to me. Here's why: …"
* Instead of "Did you even read the docs?", try "The relevant documentation
  is at …"

**Be patient with newcomers.** If someone doesn't know how things work here,
point them to the right docs or give them the context they need. Criticism
without guidance isn't helpful.


.. _mailinglists:

Mailing lists
=============

.. note::

   Mailing lists have generally been replaced by the `Discourse`_ forum.
   Specifically,

   * The python-dev list is superseded by the `Core Development`_
     and `PEPs`_ categories on Discourse.
   * The python-ideas list is superseded by posts in the `Ideas`_
     category on Discourse.

   Discussion in :guilabel:`Core Development` is focused on issues related to Python's
   own development, such as how to handle a specific issue, a PEP, etc.

   - Ideas about new functionality should **not** start here, and instead
     should be discussed in `Ideas`_.
   - Technical support questions should also not be asked here, and instead
     should go to the `Python Help`_ category on Discourse or the python-list_.

   Previous threads on the python-dev_, python-committers_, and python-ideas_
   mailing lists can be accessed through the `online archive
   <https://mail.python.org/archives/>`__.

   .. _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-ideas: https://mail.python.org/archives/list/python-ideas@python.org/

General Python questions should go to `python-list`_ or `tutor`_
or similar resources, such as `Stack Overflow`_ or the ``#python`` IRC channel
on Libera.Chat_.

The `core-workflow <https://github.com/python/core-workflow/issues>`__
issue tracker is the place to discuss and work on improvements to the CPython
core development workflow.

A complete list of Python mailing lists can be found at
https://mail.python.org/mailman3/. Some lists may also
be mirrored at `GMANE <https://gmane.io/>`__ and can be read and posted to in various
ways, including via web browsers, NNTP newsreaders, and RSS feed readers.

.. _python-list: https://mail.python.org/mailman3/lists/python-list.python.org/
.. _tutor: https://mail.python.org/mailman3/lists/tutor.python.org/
.. _Stack Overflow: https://stackoverflow.com/
.. _Libera.Chat: https://libera.chat/


.. _communication-discourse:

Discourse (discuss.python.org web forum)
========================================

We have our own `Discourse`_ forum for both developers and users.
It has different categories and most core development discussions
take place in the open forum categories for `PEPs`_ and `Core Development`_
(these are the Discourse equivalents to the python-dev mailing list).
All categories are open for users to read and post with the exception of
the `Committers`_ category, where posting is restricted to the `CPython
<https://github.com/python/cpython>`__ core team.

The Committers category is often used for announcements and notifications.
It is also the designated venue for the core team promotion votes.

Tutorials for new users
-----------------------

To start a topic or participate in any discussions in the forum, sign up and
create an account using an email address or GitHub account. You can do so by
clicking the :guilabel:`Sign Up` button on the top right hand corner of the
`Discourse`_ main page.

The Python Discourse `Quick Start <https://discuss.python.org/t/python-discourse-quick-start/116>`__
compiled by `Carol Willing <https://discuss.python.org/u/willingc/>`__ gives you
a quick overview on how to kick off Python Discourse.

We recommend new users getting familiarised with the forum by going through Discobot tutorials.
These tutorials can be activated by replying to a welcome message from "discourse
Greetings!" received under Notifications and Messages in your user account.

* Click on your personal account found on the top right hand corner of the page.
* The dropdown menu will show four different icons:
  :guilabel:`🔔` (Notifications),
  :guilabel:`🔖` (Bookmarks),
  :guilabel:`✉️` (Messages), and
  :guilabel:`👤` (Preferences).
* Select either Notifications or Messages.
* Open the "Greetings!" message sent by Discobot to start the tutorial.

Ensure that you read through the `Python Code of Conduct <https://discuss.python.org/faq>`__.
We are to be open, considerate and respectful to all users in the community.
You can report messages that don't respect the CoC by clicking on the three
dots under the message and then on the :guilabel:`⚐` icon.  You can also mention the
`@staff <https://discuss.python.org/groups/staff>`__,
`@moderators <https://discuss.python.org/groups/moderators>`__, or
`@admins <https://discuss.python.org/groups/admins>`__ groups in a message.



Reading topics
--------------

Click a topic title and read down the list of replies in chronological order,
following links or previewing replies and quotes as you go. Use your mouse to
scroll the screen, or use the timeline scroll bar on the right which also shows
you how far through the conversation you've read. On smaller screens, select the
bottom progress bar to expand it.


Notifications
-------------

Following categories (category notifications)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Notifications can be set for individual categories and topics. To change any of these
defaults, you can either go to your user preferences, or visit the category
page, and use the notification button :guilabel:`🔔` above the topic list,
on the top right hand corner of the category page beside the
:guilabel:`+ New Topic` button.

Clicking on the notification control :guilabel:`🔔` will show a drop-down panel with 5
different options: Watching, Tracking, Watching First Post, Normal, and Muted.
All categories are set by default in Normal mode where you will only be notified
if someone mentions your @name or replies to you.

Following individual threads (topic notifications)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To follow any individual topics or threads, you can adjust your notifications
through the notification button :guilabel:`🔔` found on the right of the topic at the end
of the timeline. You can also do so at the bottom of each topic.
Select "Watching" and you will be notified when there is any new updated reply
from that particular thread.

Customising notifications on user preference
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To get a bird's eye view of all your customised notifications, you can
go to `Preferences of your account <https://discuss.python.org/my/preferences/categories>`__.
This allows you to make adjustments according to categories, users, and tags.

Enabling mailing list mode
--------------------------

In mailing list mode, you will receive one email per post, as happens with
traditional mailing lists. This is desirable if you prefer to interact via email,
without visiting the forum website.
To activate the mailing list mode, go to the `email preferences
<https://discuss.python.org/my/preferences/emails>`__, check "Enable
mailing list mode" and save changes.

.. _Discourse: https://discuss.python.org/
.. _PEPs: https://discuss.python.org/c/peps/19
.. _Core Development: https://discuss.python.org/c/core-dev/23
.. _Committers: https://discuss.python.org/c/committers/5
.. _Ideas: https://discuss.python.org/c/ideas/6
.. _Python Help: https://discuss.python.org/c/help/7


Discord (private chat server)
=============================

For more real-time discussions, the core development team have a private Discord
server available. Core team members, Steering Council members, triagers, and
documentarians on the project are eligible to join the server. Joining the
Discord server is entirely optional, as all essential communications occur on
the mailing lists and Discourse forums.

For core team members, a long-lived multiple-use invitation link for this server
can be found in the private core team only section of the Discourse forum.

For triagers and documentarians joining the Discord server, a single use invitation
link should be generated and sent to them directly.

When first joining the server, new users will only have access to the ``#welcome``
and ``#rules-and-info`` channels. To link their Discord ID with their project
role, core team members may update their Steering Council 🔒 `voter record`_ with
their Discord ID before posting in the ``#welcome`` channel to request access
to the rest of the server channels. Triagers, documentarians, and core team members
that would prefer not to add their Discord ID to their Steering Council voter
record may instead be vouched for by an existing member of the Discord server.

As a private, non-archived, forum, final decisions on design and development
questions should not be made on Discord. Any conclusions from Discord discussions
should be summarised and posted to the issue tracker, Discourse forum, or
mailing list (the appropriate venue for sharing conclusions will depend on the
specific discussion).

Note: existing Discord users may want to right click on their username in the
automatic Discord welcome message and choose "Edit Server Profile" in order to
set a specific `Server Nickname`_

.. _voter record: https://github.com/python/voters/blob/main/python-core.toml
.. _Server Nickname: https://support.discord.com/hc/en-us/articles/219070107-Server-Nicknames


IRC
===

Some core team members still participate in the ``#python-dev`` IRC channel on
``irc.libera.chat``. This is not a place to ask for help with Python, but to
discuss issues related to Python's own development. See also the
``#python-dev-notifs`` channel for bots notifications.


Blogs
=====

Several core team members are active bloggers and discuss Python's development
that way. You can find their blogs (and various other developers who use Python)
at `Planet Python <https://planetpython.org/>`__.


Setting expectations for open-source participation
==================================================

Burn-out is common in open source due to a misunderstanding of what users, contributors,
and maintainers should expect from each other. Brett Cannon gave a `talk <https://www.youtube.com/watch?v=-Nk-8fSJM6I>`__
about this topic that sets out to help everyone set reasonable expectations of each other in
order to make open source pleasant for everyone involved.

Additional repositories
=======================

`Python Core Workflow`_ hosts an issue tracker for workflow discussions.

Some core workflow tools are:

* `cherry_picker`_ (:pypi:`PyPI <cherry_picker>`)
* `bedevere`_
* `blurb`_ (:pypi:`PyPI <blurb>`)
* `blurb_it`_
* `miss-islington`_
* `clabot`_
* `webhook-mailer`_

Python `Performance Benchmark`_ project is intended to be an authoritative
source of benchmarks for all Python implementations.

.. _Python Core Workflow: https://github.com/python/core-workflow
.. _cherry_picker: https://github.com/python/cherry-picker
.. _bedevere: https://github.com/python/bedevere
.. _blurb: https://github.com/python/blurb
.. _blurb_it: https://github.com/python/blurb_it
.. _miss-islington: https://github.com/python/miss-islington
.. _clabot: https://github.com/psf/clabot
.. _webhook-mailer: https://github.com/python/webhook-mailer
.. _Performance Benchmark: https://github.com/python/pyperformance