Add November 2025 minutes

docs/monthly-meeting/2025-11.md

@@ -0,0 +1,172 @@
+# Documentation Community Team Meeting (November 4, 2025)
+
+## Roll call
+
+(Name / `@GitHubUsername` _[/ Discord, if different]_)
+
+- Hugo van Kemenade / `@hugovk`
+- Adam Turner / `@AA-Turner`
+- Ned Batchelder / `@nedbat`
+- Nathan Goldblum / `@ngoldblum`
+- Blaise Pabon / `@blaisep` / `controlpl4n3`
+- Ryan Duve / `@ryan-duve`
+
+## Introductions
+
+> If there are any new people, we should do a round of introductions.
+
+We had a round.
+
+## Reports and celebrations
+
+None this time.
+
+## Discussion
+
+- [Lysandros/Nathan] CPython free-threading (FT) docs
+  - https://py-free-threading.github.io
+  - [gh-137232: Update free-threading HOWTOs with up-to-date info for 3.14](https://github.com/python/cpython/pull/140817)
+  - [gh-140374: Add glossary entries related to multithreading](https://github.com/python/cpython/pull/140375)
+  - [Quansight-Labs/free-threaded-compatibility#261](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/261)
+  - [Nathan] Lys is concentrating on improving CPython docs for FT, unfortunately
+    couldn't attend this meeting due to a conflict.
+  - Steering Council said let's make https://py-free-threading.github.io part of
+    docs.python.org as a subdomain.
+  - A big new batch of docs by the FT team was
+    [recently relicensed](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/249#issuecomment-3221471102)
+    from MIT to 0BSD + MIT so we can upstream to the CPython docs.
+  - It uses MKDocs.
+  - Feedback from Sam Gross and Thomas Wouters: it would be best to avoid making
+    huge changes to existing docs.
+  - But what is as minimal as possible?
+  - Feedback from docs editorial team: keep on own page.
+  - Have already made PRs to improve glossary, how-tos, and more upstreamed from FT
+    guide.
+  - Want clarity on how to move forward.
+  - The plan is in
+    [Quansight-Labs/free-threaded-compatibility#261](https://github.com/Quansight-Labs/free-threaded-compatibility/issues/261).
+  - [Adam] Would like to avoid the glossary being a general programming resource.
+  - [Nathan] Good feedback, if entries need to exist, it's because of CPython's needs.
+  - [Ned] Not so convinced if they should only relate to Python, it's a difficult
+    balance. Now we're looking through that lens, how many other entries would be
+    excluded with that rule?
+  - [Adam] There was a general discussion on this topic at the Cambridge core sprint, no
+    actions created. How tight do we make the FT docs its own area vs. putting them
+    throughout general docs? For example, do we add notes on `list` about being atomic
+    in stdtypes, or have an FT reference section somewhere with all the common container
+    considerations? The latter was preferred. Is it realistic to put all the relevant
+    concerns on a single page?
+  - [Nathan] The next big task for Lys is to look at the big types and work out safety
+    guarantees. For example, it's not safe to share iterators across threads, and
+    memoryviews have considerations. Need to list them somewhere. `list` and `dict` will
+    be pretty straightforward, atomic for the most part. Others will be complicated. It
+    depends on how much there is to say for each. Some things are ready for 3.15, but
+    weren't for 3.14. At least for builtins, we'll write this down in a big table, then
+    it'll be easier to figure out how to integrate it.
+  - [Adam] Yes, this will help. Also, a difference between thread-safety concerns in the
+    abstract, and relating to free-threading. For example, sharing data structure
+    between threads, already concerns in older versions. How do we document thread
+    safety with a nod to FT, while not cluttering things up?
+    Many programmers will only use single-threaded.
+    We'll want to point them to higher abstract things.
+  - [Nathan] Should document it, people should assume types are not safe to share between
+    threads. `list`/`dict` being atomic should be clearly documented. Per-module docs
+    can help a lot, if we can add a FT section. Matthias Bussonnier is looking to
+    improve ecosystem docs, for example, the NumPy docs need an FT section.
+    Need to figure out where to draw line.
+  - [Ned] Not sure about a regular thread-safety section, as Adam mentioned, tends to be an
+    advanced topic and for the most part you don't need to worry about it. For example,
+    `list` could say threads are atomic, see elsewhere for more about this. Otherwise,
+    spread throughout docs seems a bit lopsided. We've been fixing flaws in the
+    language, but doesn't need to be top of mind for most readers. For example, we don't
+    say list access is _O_(1) and so on. People say that's an implementation detail.
+    FT is also an implementation detail.
+  - [Nathan] The broader point is how to document implementation details.
+    Will try and make minimal changes to docs, but add when thread-safe or not.
+    How would readers get to a thread-safety page?
+    How to get there from stdlib module pages? Are there links?
+  - [Ned] Seems reasonable to have links sprinkled throughout docs to the main page:
+    "Are you using FT? Go here".
+  - [Adam] We have availability notes: "Availability: Unix, not WASI". We could do
+     the same for FT. The concern is how far up the discoverability chain do we put it. A
+    12-year-old reading `list` docs don't need to know about thread safety, an advanced
+    programmer might. Should be aiming so using Python just works, keep simple things
+    easy. Only when run into something complex do you need to go to thread-safety
+    guarantees. So a link for every type with a tick or cross is an antipattern. I think
+    this touches on the py-free-threading guide, I don't think it should exist, it would
+    be a shame to bifurcate the docs like that. Advanced topics should be in the main
+    docs. Would rather make its way into main docs. The FT tracker is probably right to
+    stay external, don't need to upstream everything.
+  - [Adam] Want advanced docs there if needed, but don't want to scare people with
+    thread-safety warnings everywhere if not needed. Can mention `list`/`dict` are safe.
+    Extensions should have a statement like: "assume not thread-safety".
+  - [Nathan] Idea: maybe a data model page, like in Java, that goes over things like
+    thread-safety, and thinking about threading in Python.
+  - [Ned] How to find it?
+  - [Adam] Reasonable idea. Having more reference docs. Too much runtime init/model stuff
+    are in C API docs and should be moved to the main reference. What are
+    language/implementation guarantees? Docs about model seems reasonable. Once written,
+    getting it in front of people is easier, when it exists. SEO will help.
+  - [Nathan] Will start linking when it exists.
+  - [Ned] Get the words written, then we can move and improve.
+    Does Python have a crisp data model page, when we have 30 years of organic growth?
+  - [Nathan] Java went the other way. No draft yet of the page. Lys is working on
+    an overview of all builtins, which will inform this. We have
+    https://docs.python.org/3/reference/datamodel.html, but it's out of date, mentions
+    GIL, some stuff is wrong. Will need to fix it as part of this.
+  - [Ned] And it's too long.
+  - [Adam] Skimming the current FT guide, maybe about half make sense to upstream.
+    Definitely the porting guide, and subinterpreters.
+  - [Nathan] And Cython and pybind11?
+  - [Adam] For the C API. Good to upstream frequently seen errors.
+  - [Nathan] Almost all is ecosystem docs.
+    It would be helpful to link to Cython docs on this and the others from CPython docs.
+  - [Adam] Willing to link externally.
+  - [Ned] If upstreamed, do we still need a separate guide?
+  - [Nathan] Yes, because a lot is needed for details about Cython or PY03 etc. many
+    building via bindings generators and not C API directly.
+  - [Ned] Willing to upstream for the C API. Would we insist on this,
+    or better to have it in one place if it only applies to C API?
+  - [Nathan] The existing porting guide is pretty good, already upstreamed what makes
+    sense. Maybe need general considerations, content not necessarily about C API, and
+    extensions in general, what to avoid, using critical section, so you understand what
+    it means. Some level of CPython docs for extension authors, doesn't need to go into
+    details about generators or C API.
+  - [Adam] If FT becomes default, what's the situation then? Would we still want a
+    py-free-threading guide? We've not really done this for other language features. As
+    a transition thing, it's a really good resource. But from a 10-year perspective,
+    wouldn't I want to reach for projects' own docs first? And C API docs directly?
+  - [Nathan] the relevant stuff should be in the CPython docs. Would be good to have
+    https://py-free-threading.github.io/porting-extensions/#working-with-the-free-threaded-cpython-interpreter-runtime
+    in docs: detaching/attaching/GIL stuff. How to think about blocking calls, deadlock
+    with interpreter, general content about how to work with C API but it's for all
+    extension authors. All can link to these docs.
+  - [Adam] For consumers of C API. Have you spoken to the C API WG?
+  - [Nathan] Not about docs. Thread-safety notes about C API are less pressing than
+    notes that more will see. What's your take on adding thread-safety to C API docs?
+  - [Adam] Important, but less interested personally. Petr is an expert here.
+    Can ask when Petr and Lys are both present next time.
+  - [Nathan] Can convert to Sphinx if needed when upstreaming.
+  - [Blaise] Petr has a weekly stream working on the grammar docs, can also do office
+    hours stuff. No need to wait until next month's meeting. The event in this Discord,
+    welcome to drop in.
+  - [Nathan] We want more eyes on this stuff. It would be helpful if you could chime in on the
+    tracking issue above. More expert eyes on the docs before upstreaming will help.
+    More about improving CPython docs than porting the whole thing over and overwhelming
+    a 12-year-old. Better to document the positive things, can also mention some
+    here-be-dragons.
+  - [Ned] The current docs aren't great at dealing with the implementation-specific aspect,
+    so maybe we'll flex those muscles getting these in.
+  - [Nathan] Find a way to doc implementation details, subject to change, so people don't
+    rely on them.
+  - [Ned] We have some, but in weird corners.
+  - [Adam] Don't have a policy.
+
+
+- [Ned] See [python/devguide#1679](https://github.com/python/devguide/pull/1679)
+  a PR on use of AI, in case you want to chime in.
+
+
+- [Blaise] tutorials: has there been a discussion on learning objectives for different
+  scenarios.
+  - [Ned] It's difficult to speak with one voice, users are so diverse. So many paths.

docs/monthly-meeting/index.rst

@@ -27,3 +27,4 @@ Monthly reports in chronological order.
    Aug 2025 <2025-08.md>
    Sep 2025 <2025-09.md>
    Oct 2025 <2025-10.md>
+   Nov 2025 <2025-11.md>