diff --git a/docs/monthly-meeting/2025-11.md b/docs/monthly-meeting/2025-11.md new file mode 100644 index 0000000..6342799 --- /dev/null +++ b/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. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index 8865c76..09a6f5a 100644 --- a/docs/monthly-meeting/index.rst +++ b/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>