Skip to content

Commit b9aa783

Browse files
hugovkStanFromIreland
hugovk
and
StanFromIreland
authored
Add November 2025 minutes (#169)
Co-authored-by: Stan Ulbrych <[email protected]>
1 parent e9fb5f2 commit b9aa783

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

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

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