diff --git a/docs/monthly-meeting/2024-08.md b/docs/monthly-meeting/2024-08.md new file mode 100644 index 0000000..ed15de2 --- /dev/null +++ b/docs/monthly-meeting/2024-08.md @@ -0,0 +1,88 @@ +# Documentation Community Team Meeting (August 2024) + +- **Date:** 2024-08-06 +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-08-06/19:00/Docs%20Meeting) +- **This HackMD:** +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-6th-august-2024/59599) (for August) +- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls)) +- **Calendar event:** (send your e-mail to Mariatta for an invitation) +- **How to participate:** + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. + - To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). + You need to log in (e.g. with a GitHub account). + +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). +Please take a second to read through it! + +## Roll call + +(Name / `@GitHubUsername` *[/ Discord, if different]*) + +- Hugo van Kemenade / `@hugovk` +- Ezio Melotti / `@ezio-melotti` +- Trey / `@treyhunner` +- Manuel / `@humitos` +- Ned Batchelder / `@nedbat` +- Petr Viktorin / `@encukou` +- Usman +- Carol / `@willingc` +- Daniele / `@EvilDMP` + +## Reports and celebrations + +- [Manuel] Moving the docs to Read the Docs + - Several reasons: be more open (let everyone see if the builds failed, how the builds work); faster builds; + - A test is already working for pull requests. Only PRs that touch documentation are built. + - Test: + - [python/docs-community#5](https://github.com/python/docs-community/issues/5) + - In the last 1-2 months, we've been working on the language and version selector. In the current process this is added at build time from a JSON file, RTD does that at serve time with Javascript so even old versions of the docs link to current versions. + - We've been working to not losing what we already have but also not get rid of RTD features. + - 3.13 or 3.14 is the version we'll migrate first, to get a feel for the workflow. All other versions will be served by python.org for now. Then we'll migrate one version at a time. + - [Trey] Will this enhance the search? [Manuel] There have been many improvements in RTD search lately. Traditionally RTD overwrites Sphinx search entirely with server-side (Elastic Search) search. Now there's a way to choose RTD or Sphinx search from the docs theme. There's also a person who said they're working on the Sphinx sphinx search engine. + - [Trey] So there won't be a change on day one. + - [Carol] For the PR previews, is there an option to link to the most changed file in the PR? [Manuel] We're working on it, don't know the details. The idea is to perform a diff and determine what changed, and link to it directly. + - Issue: [readthedocs/readthedocs.org#11319](https://github.com/readthedocs/readthedocs.org/issues/11319) + - Design doc: [readthedocs/readthedocs.org#11507](https://github.com/readthedocs/readthedocs.org/pull/11507) + - [Carol] That's way further ahead than I thought. Thank you! + +## Discussion + +[Ezio] Deprecations in the What's New file - replacing the list of deprecations with a table +- [Hugo] We previously talked about putting deprecations in include files. We have that now: +- Compare and +- *Some notes compiled after the meeting:* + - improving deprecation notes: explain how to replace the deprecated API, either in the note, or in a section at the bottom of the module's doc + - duplication: ensure that the deprecation notes only exist in a single place without duplication (links to it and includes in multiple places are fine) + - discoverability: making sure that people can easily find what is being deprecated and removed, and how to fix it + - future-proofing: make sure these info are not completely removed from the latest docs (a link to older versions is fine) + - layout: list vs table (see [python/cpython#122652](https://github.com/python/cpython/issues/122652)), next step is to create a table as a proof of concept to see what works best +- *Some additional links:* + - python-dev thread from a decade ago: (some of these things are fixed, some are no longer relevant, some still need work) + - Enforcing the use of deprecated-removed: [python/cpython#92564](https://github.com/python/cpython/issues/92564) + - A related core-workflow issue: [python/core-workflow#468](https://github.com/python/core-workflow/issues/468) + - Moving deprecations into include files: [python/cpython#122085](https://github.com/python/cpython/issues/122085) +- Next step: add a demo of how the table would look + +[Ezio] Defining and documenting a procedure to ensure that we follow up on additional tasks brought up in review +- [python/devguide#1359](https://github.com/python/devguide/issues/1359) +- [Hugo] If someone says “let's do this”, they should be in charge of who's going to do it +- [Ezio] There's a “diffusion of responsibility”, we should define who should go and open the issue to follow up. The proposal is that the PR author should be in charge -- either volunteer to follow up or find other actors to do it. +- [Carol] One thing we've done on other projects is that the person who proposes additional work should open that issue; then it's fair game for anyone to pick it up. +- [Ezio] One reason I mentioned the author of the PR is that someone could come and see an issue, but they don't have the context that the PR author has. + +[#118891 Slow actions for doc builds](https://github.com/python/cpython/issues/118891) + +### PEP Workflow + +- [PEP 750: Tag strings for writing domain specific languages](https://github.com/python/peps/pull/3858) FYI + +## Follow-ups from previous meeting(s) + +*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)* + +## Next meeting + +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. + +We have a recurring Google Calendar event for the meeting. +Let Mariatta know your email address and she can invite you. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index ade6850..149c550 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -23,3 +23,4 @@ Monthly reports in chronological order. May 2024 <2024-05.md> Jun 2024 <2024-06.md> Jul 2024 <2024-07.md> + Aug 2024 <2024-08.md>