Skip to content

Commit 82cdff6

Browse files
hugovkhugovk
committed
Add November 2025 minutes
1 parent e9fb5f2 commit 82cdff6

File tree

2 files changed

+174
-0
lines changed

2 files changed

+174
-0
lines changed

‎docs/monthly-meeting/2025-11.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Documentation Community Team Meeting (November 4, 2025)
2+
3+
## Roll call
4+
5+
(Name / `@GitHubUsername` _[/ Discord, if different]_)
6+
7+
- Hugo van Kemenade / `@hugovk`
8+
- Adam Turner / `@AA-Turner`
9+
- Ned Batchelder / `@nedbat`
10+
- Nathan Goldblum / `@ngoldblum`
11+
- Blaise Pabon / `@blaisep` / `controlpl4n3`
12+
- Ryan Duve / `@ryan-duve`
13+
14+
## Introductions
15+
16+
> If there are any new people, we should do a round of introductions.
17+
18+
We had a round.
19+
20+
## Reports and celebrations
21+
22+
None this time.
23+
24+
## Discussion
25+
26+
- [Lysandros/Nathan] CPython free-threading (FT) docs
27+
- https://py-free-threading.github.io
28+
- [gh-137232: Update free-threading HOWTOs with up-to-date info for 3.14](https://github.com/python/cpython/pull/140817)
29+
- [gh-140374: Add glossary entries related to multithreading](https://github.com/python/cpython/pull/140375)
30+
- [Quansight-Labs/free-threaded-compatibility#261](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/261)
31+
- Nathan:
32+
- Lys is concentrating on improving CPython docs for FT, unfortunately couldn't attend
33+
this meeting due to a conflict
34+
- Steering Council said let's make https://py-free-threading.github.io part of
35+
docs.python.org as a subdomain
36+
- A big new batch of docs by the FT team was
37+
[recently relicensed](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/249#issuecomment-3221471102)
38+
from MIT to 0BSD + MIT so can upstream to CPython docs
39+
- Uses MKDocs
40+
- Feedback from Sam Gross and Thomas Wouters: would be best to avoid making huge
41+
changes to existing docs
42+
- But what is as minimal as possible?
43+
- Feedback from docs editorial team: keep in own page
44+
- Have already made PRs to improve glossary, how-tos, and more upstreamed from FT
45+
guide
46+
- want clarity on how to move forward
47+
- The plan is in
48+
[Quansight-Labs/free-threaded-compatibility#261](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/261)
49+
- Adam: would like to avoid glossary being general programming resource
50+
- Nathan: good feedback, if entries need to exist, it's because of CPython's needs
51+
- Ned: not so convinced if they should only relate to Python, it's a difficult
52+
balance. Now we're looking through that lense, how many other entries would be
53+
excluded with that rule?
54+
- Adam: There was a general discussion on this topic at the Cambridge core sprint, no
55+
actions created. How tight do we make the FT docs its own area vs. putting them
56+
throughout general docs? For example, do we add notes on `list` about being atomic
57+
in stdtypes, or have an FT reference section somewhere with all the common container
58+
considerations? The latter was preferred. Is it realistic to put all the relevant
59+
concerns on a single page?
60+
- Nathan: the next big task for Lys is to look at the big types and work out safety
61+
guarantees. For example, it's not safe to share iterators across threads, and
62+
memoryviews have considerations. Need to list them somewhere. `list` and `dict` will
63+
be pretty straightforward, atomic for the most part. Others will be complicated. It
64+
depends on how much there is to say for each. Some things are ready for 3.15, but
65+
weren't for 3.14. At least for builtins, we'll write this down in a big table, then
66+
it'll be easier to figure out how to integrate it.
67+
- Adam: yes, this will help. Also a difference between thread-safety concerns in the
68+
abstract, and relating to free-threading. For example, sharing data structure
69+
between threads, already concerns in older versions. How do we document thread
70+
safety with a nod to FT, and not cluttering things up? Many programmers will only
71+
use single-threaded. We'll want to point them to higher abstract things.
72+
- Nathan: should document, people should assume types are not safe to share between
73+
threads. `list`/`dict` being atomic should be clearly documented. Per-module docs
74+
can help a lot, if we can add a FT section. Matthias Bussonnier is looking to
75+
improve ecosystem docs, for example, NumPy docs need an FT section. Need to figure
76+
out where to draw line.
77+
- Ned: not sure about regular thread-safety section, as Adam mentioned, tends to be an
78+
advanced topic and for most part you don't need to worry about it. For example,
79+
`list` could say threads are atomic, see elsewhere for more about this. Otherwise
80+
spread throughout docs seems a bit lopsided. We've been fixing flaws in the
81+
language, but doesn't need to be top of mind for most readers. For example, we don't
82+
say list access is _O_(1) and so on. People say that's an implementation detail. FT
83+
is also an implementation detail.
84+
- Nathan: the broader point is how to doc implementation details. Will try and make
85+
minimal changes to docs, but add when thread-safe or not. How would readers get to a
86+
thread-safety page? How to get from stdlib module pages? Are there links?
87+
- Ned: seems reasonable to have links sprinkled throughout docs to main page. "Are you
88+
using FT? Go here".
89+
- Adam: we have availability notes ;ole "availability: Unix, not WASI". could do
90+
similar for FT. The concern is how far up the discoverability chain do we put it. A
91+
12-year-old reading `list` docs don't need to know about thread safety, an advanced
92+
programmer might. Should be aiming so using Python just works, keep simple things
93+
easy. Only when run into something complex do you need to go to thread-safety
94+
guarantees. So a link for every type with a tick or cross is an antipattern. I think
95+
this touches on the py-free-threading guide, I don't think it should exist, it would
96+
be a shame to bifurcate the docs like that. Advanced topics should be in the main
97+
docs. Would rather make its way into main docs. The FT tracker is probably right to
98+
stay external, don't need to upstream everything.
99+
- Adam: want advanced docs there if needed, but don't want to scare people with
100+
thread-safety warnings everywhere if not needed. Can mention `list`/`dict` are safe.
101+
Extensions should have a statement like: "assume not thread-safety".
102+
- Nathan: idea: maybe a data model page, like Java, that goes over things like
103+
thread-safety, and thinking about threading in Python.
104+
- Ned: How to find it?
105+
- Adam: Reasonable idea. Having more reference docs. Too much runtime init/model stuff
106+
are in C API docs and should be moved to the main reference. What are
107+
language/implementation guarantees? Docs about model seems reasonable. Once written,
108+
getting it in front of people is easier, when it exists. SEO will help.
109+
- Nathan: Will start linking when it exists.
110+
- Ned: Get the words written, then we can move and improve. Does Python have a crisp
111+
data model page, when we have 30 years of organic growth?
112+
- Nathan: Java went the other way. No draft yet of the page. Lys is working on
113+
overview of all builtins, which will inform this. We have
114+
https://docs.python.org/3/reference/datamodel.html but it's out of date, mentions
115+
GIL, some stuff is wrong. Will need to fix it as part of this.
116+
- Ned: and it's too long.
117+
- Adam: skimming current FT guide, maybe about half make sense to upstream. Definitely
118+
porting guide, and subinterpreters/
119+
- Nathan: and Cython and pybind11?
120+
- Adam: for C API. Good to upstream frequently seen errors.
121+
- Nathan: Almost all is ecosystem docs. Would be helpful to link to Cython docs on
122+
this and the others from CPython docs.
123+
- Adam: willing to link externally.
124+
- Ned: if upstreamed, do we still need a separate guide?
125+
- Nathan: yes, because a lot is needed for details about Cython or PY03 etc. many
126+
building via bindings generators and not C API directly.
127+
- Ned: willing to upstream for the C API. Would we insist on this, or better to have
128+
in one place if it only applies to C API?
129+
- Nathan: the existing porting guide is pretty good, already upstreamed what makes
130+
sense. Maybe need general considerations, content not necessarily about C API, and
131+
extensions in general, what to avoid, using critical section, so you understand what
132+
it means. Some level of CPython docs for extension authors, doesn't need to go into
133+
details about generators or C API.
134+
- Adam: if FT becomes default, what's the situation then? Would we still want a
135+
py-free-threading guide? We've not really done this for other language features. As
136+
a transition thing, it's a really good resource. but for a 10-year perspective,
137+
wouldn't I want to reach for projects' own docs first? And C API docs directly?
138+
- Nathan: the relevant stuff should be in the CPython docs. Would be good to have
139+
https://py-free-threading.github.io/porting-extensions/#working-with-the-free-threaded-cpython-interpreter-runtime
140+
in docs: detaching/attaching/GIL stuff. How to think about blocking calls, deadlock
141+
with interpreter, general content about how to work with C API but it's for all
142+
extension authors. All can link to these docs.
143+
- Adam: for consumers of C API. have you spoken to C API WG?
144+
- Nathan: not about docs. thread-safety notes about C API is less pressing than for
145+
notes that more will see. what's your take on thread-safety to C API docs?
146+
- Adam: important, but less interested personally. Petr is expert here. can ask when
147+
Petr and Lys both present next time.
148+
- Nathan: can convert to Sphinx if needed when upstreaming.
149+
- Blaise: Petr has a weekly stream working on the grammar docs, can also do office
150+
hours stuff. No need to wait until next month's meeting. The event in this Discord,
151+
welcome to drop in.
152+
- Nathan: we want more eyes on this stuff. Would be helpful if you can chime in on the
153+
tracking issue above. More expert eyes on the docs before upstreaming will help.
154+
More about improving CPython docs than porting the whole thing over and overwhelming
155+
a 12-year-old. Better to document the positive things, can also mention some
156+
here-be-dragons.
157+
- Ned: current docs aren't great at dealing with the implementation specific aspect,
158+
so maybe we'll flex those muscles getting these in.
159+
- Nathan: find a way to doc implementation details, subject to change, so people don't
160+
rely on them.
161+
- Ned: we have some, but in weird corners.
162+
- Adam: don't have a policy.
163+
164+
---
165+
166+
- [Ned] See https://github.com/python/devguide/pull/1679 PR on use of AI, in case want
167+
to chime in
168+
169+
---
170+
171+
- [Blaise] tutorials: has there been a discussion on learning objectives for different
172+
scenarios.
173+
- Ned: it's difficult to speak with one voice, users so diverse. So many paths.

‎docs/monthly-meeting/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@ Monthly reports in chronological order.
2727
Aug 2025 <2025-08.md>
2828
Sep 2025 <2025-09.md>
2929
Oct 2025 <2025-10.md>
30+
Nov 2025 <2025-11.md>

0 commit comments

Comments
 (0)