Skip to content

Commit 15ba40f

Browse files
georgicallyezio-melottierlend-aasland
authored
gh-853: Update Document Discourse. (#876)
* Update Document Discourse issue #853 * fix whitespaces * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * minor adjustments to discourse doc updates * Update communication.rst Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com> * Update communication.rst Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com> * Update communication.rst Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com> * Update communication.rst Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com> * updated suggested changes * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * adjusted redundant info on notifications * resolve merge conflict * minor adjustment * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Update communication.rst Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> * Add note about flagging messages and pinging staff. * Remove trailing whitespace. * Add Discourse groups links to `linkcheck_ignore`. * Move a link. Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
1 parent 989b8c1 commit 15ba40f

File tree

3 files changed

+103
-17
lines changed

3 files changed

+103
-17
lines changed

‎communication.rst‎

Lines changed: 88 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -99,21 +99,94 @@ We have our own `Discourse`_ forum for both developers and users. This forum
9999
complements the `python-dev`_, `python-ideas`_, `python-help`_, and
100100
`python-list`_ mailing lists.
101101

102-
Most core development discussions take place in the open forum categories for
103-
`PEPs`_ and `Core Development`_. (These are the Discourse equivalents to the
104-
python-dev mailing list)
105-
106-
The `Committers`_ category restricts posting to core developers only, and is
107-
used more for announcements and notifications, rather than for discussions. It
108-
is also the venue for core developer promotion votes. (This category is the
109-
equivalent of the python-committers mailing list)
110-
111-
There is a final, rarely used, core development category on Discourse that is
112-
only visible to core developers. This can be used to share administrative
113-
information with all core developers in a non-public forum (e.g. logistics for
114-
in person core development sprints), as well as for individual core developers
115-
to share info that they'd like other core devs to be aware of, but would prefer
116-
not to have permanently archived on the internet.
102+
This forum has different categories and most core development discussions
103+
take place in the open forum categories for `PEPs`_ and `Core Development`_
104+
(these are the Discourse equivalents to the python-dev mailing list).
105+
All categories are open for users to read and post with the exception of
106+
the `Committers`_ category, where posting is restricted to the `CPython
107+
<https://github.com/python/cpython>`_ core developers.
108+
109+
The Committers category is often used for announcements and notifications.
110+
It is also a common venue for the core developer promotion votes (this
111+
category is equivalent to the python-committers mailing list).
112+
113+
Tutorials for new users
114+
'''''''''''''''''''''''
115+
To start a topic or participate in any discussions in the forum, sign up and
116+
create an account using an email address or GitHub account. You can do so by
117+
clicking the "Sign Up" button on the top right hand corner of the `Discourse`_
118+
main page.
119+
120+
The Python Discourse `Quick Start <https://discuss.python.org/t/python-discourse-quick-start/116>`_
121+
compiled by `Carol Willing <https://discuss.python.org/u/willingc/>`_ gives you
122+
a quick overview on how to kick off Python Discourse.
123+
124+
We recommend new users getting familiarised with the forum by going through Discobot tutorials.
125+
These tutorials can be activated by replying to a welcome message from "discourse
126+
Greetings!" received under Notifications and Messages in your user account.
127+
128+
* Click on your personal account found on the top right hand corner of the page.
129+
* The dropdown menu will show four different icons: 🔔 (Notifications),
130+
🔖 (Bookmarks), ✉️ (Messages), and 👤 (Preferences).
131+
* Select either Notifications or Messages.
132+
* Open the "Greetings!" message sent by Discobot to start the tutorial.
133+
134+
Ensure that you read through the `Python Code of Conduct <https://discuss.python.org/faq>`_.
135+
We are to be open, considerate and respectful to all users in the community.
136+
You can report messages that don't respect the CoC by clicking on the three
137+
dots under the message and then on the ⚐ icon. You can also mention the
138+
`@staff <https://discuss.python.org/groups/staff>`_,
139+
`@moderators <https://discuss.python.org/groups/moderators>`_, or
140+
`@admins <https://discuss.python.org/groups/admins>`_ groups in a message.
141+
142+
143+
144+
Reading topics
145+
'''''''''''''''
146+
Click a topic title and read down the list of replies in chronological order,
147+
following links or previewing replies and quotes as you go. Use your mouse to
148+
scroll the screen, or use the timeline scroll bar on the right which also shows
149+
you how far through the conversation you've read. On smaller screens, select the
150+
bottom progress bar to expand it.
151+
152+
153+
Notifications
154+
'''''''''''''
155+
156+
Following categories (Category notifications)
157+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
158+
Notifications can be set for individual categories and topics. To change any of these
159+
defaults, you can either go to your user preferences, or visit the category
160+
page, and use the notification button 🔔 above the topic list,
161+
on the top right hand corner of the category page beside the "+ New Topic" button.
162+
163+
Clicking on the Notification control 🔔 will show a drop-down panel with 5
164+
different options: Watching, Tracking, Watching First Post, Normal, and Muted.
165+
All categories are set by default in Normal mode where you will only be notified
166+
if someone mentions your @name or replies to you.
167+
168+
Following individual threads (Topic notifications)
169+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
170+
To follow any individual topics or threads, you can adjust your notifications
171+
through the notification button 🔔 found on the right of the topic at the end
172+
of the timeline. You can also do so at the bottom of each topic.
173+
Select "Watching" and you will be notified when there is any new updated reply
174+
from that particular thread.
175+
176+
Customising notifications on user preference
177+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
178+
To get a bird's eye view of all your customised notifications, you can
179+
go to `Preferences of your account <https://discuss.python.org/my/preferences/categories>`_.
180+
This allows you to make adjustments according to categories, users, and tags.
181+
182+
Enabling mailing list mode
183+
''''''''''''''''''''''''''
184+
In mailing list mode, you will receive one email per post, as happens with
185+
traditional mailing lists. This is desirable if you prefer to interact via email,
186+
without visiting the forum website.
187+
To activate the mailing list mode, go to the `email preferences
188+
<https://discuss.python.org/my/preferences/emails>`_, check "Enable
189+
mailing list mode" and save changes.
117190

118191
.. _Discourse: https://discuss.python.org/
119192
.. _PEPs: https://discuss.python.org/c/peps/

‎conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,6 +232,10 @@
232232
'https://github.com/python/voters/',
233233
# The python-core team link is private, redirects to login
234234
'https://github.com/orgs/python/teams/python-core',
235+
# The Discourse groups are private unless you are logged in
236+
'https://discuss.python.org/groups/staff',
237+
'https://discuss.python.org/groups/moderators',
238+
'https://discuss.python.org/groups/admins',
235239
]
236240

237241
# Use our custom CSS stylesheet to differentiate us from the official python

‎help.rst‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,21 @@ question.
1515
Discourse
1616
---------
1717

18-
Python has a hosted `Discourse`_ instance. Be sure to visit the related Core
18+
Python has a hosted `Discourse`_ instance. This forum has many different
19+
categories and most core development discussions take place in the open forum
20+
categories for `PEPs`_ and `Core Development`_ .
21+
Most categories are open for all users to read and post with the exception of
22+
Committers and Core Development categories. Be sure to visit the related Core
1923
categories, such as
2024
`Core Development <https://discuss.python.org/c/core-dev/23>`_ and
2125
`Core Workflow <https://discuss.python.org/c/core-workflow/8>`_.
2226

23-
.. _Discourse: https://discuss.python.org/
27+
.. seealso::
28+
`Discourse <https://devguide.python.org/communication/#discourse-discuss-python-org-web-forum>`_
29+
on how to get started.
30+
31+
32+
.. _PEPs: https://discuss.python.org/c/peps/
2433

2534
Mailing Lists
2635
-------------

0 commit comments

Comments
 (0)