Merge pull request #1 from StanFromIreland/november-stans

Author: hugovk

docs/monthly-meeting/2025-11.md

@@ -28,66 +28,67 @@ None this time.
   - [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
+  - [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
+    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 can upstream to CPython docs
-  - Uses MKDocs
-  - Feedback from Sam Gross and Thomas Wouters: would be best to avoid making huge
-    changes to existing docs
+    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 in own page
+  - 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
+    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 glossary being 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 lense, how many other entries would be
+    [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
+  - [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
+  - [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
+  - [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, and not cluttering things up? Many programmers will only
-    use single-threaded. We'll want to point them to higher abstract things.
-  - Nathan: should document, people should assume types are not safe to share between
+    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, NumPy docs need an FT section. Need to figure
-    out where to draw line.
-  - Ned: not sure about regular thread-safety section, as Adam mentioned, tends to be an
-    advanced topic and for 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
+    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 doc 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 from stdlib module pages? Are there links?
-  - Ned: seems reasonable to have links sprinkled throughout docs to main page. "Are you
-    using FT? Go here".
-  - Adam: we have availability notes ;ole "availability: Unix, not WASI". could do
-    similar for FT. The concern is how far up the discoverability chain do we put it. A
+    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
@@ -96,78 +97,76 @@ None this time.
     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
+  - [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 Java, that goes over things like
+  - [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
+  - [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
-    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
+  - [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 current FT guide, maybe about half make sense to upstream. Definitely
-    porting guide, and subinterpreters/
-  - Nathan: and Cython and pybind11?
-  - Adam: for C API. Good to upstream frequently seen errors.
-  - Nathan: Almost all is ecosystem docs. 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
+  - [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
-    in one place if it only applies to C API?
-  - Nathan: the existing porting guide is pretty good, already upstreamed what makes
+  - [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
+  - [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 for a 10-year perspective,
+    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
+  - [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 C API WG?
-  - Nathan: not about docs. thread-safety notes about C API is less pressing than for
-    notes that more will see. what's your take on thread-safety to C API docs?
-  - Adam: important, but less interested personally. Petr is expert here. can ask when
-    Petr and Lys 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
+  - [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. Would be helpful if you can chime in on the
+  - [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: current docs aren't great at dealing with the implementation specific aspect,
+  - [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
+  - [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] We have some, but in weird corners.
+  - [Adam] Don't have a policy.
 
----
 
-- [Ned] See https://github.com/python/devguide/pull/1679 PR on use of AI, in case want
-  to chime in
+- [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 so diverse. So many paths.
+  - [Ned] It's difficult to speak with one voice, users are so diverse. So many paths.