| 28 Jun 2026 |
 emily | my thinking is that the PR checklist itself should be minimal and focused on the high-importance stuff you should be checking every PR, and then first-time contributors get a bot reply with extra checkboxes for stuff we want people to learn about at the start | 21:09:36 |
 kuflierl | To be fair, i did the first 2 times or so. I don't anymore since i think i now most of it | 21:09:37 |
| emily | and the reward for those is you get the PR assigned to a round-robin new user contribution triage team | 21:09:49 |
 Grimmauld (any/all) | how would the new user interact with the bot checkboxes? You need committer to edit things | 21:10:42 |
| kuflierl | I like this. Reading it the first time was a hasle. I would have loved having a checklist + links to further questions | 21:10:48 |
| kuflierl | * I like this. Reading it the first time was a hasle. I would have loved having a checklist + links to further questions and deep dives | 21:11:28 |
| emily | yeah, the actual docs also ideally need reworking to be more readable and have a better hierarchy of information / gradual disclosure of detail according to importance… | 21:12:03 |
| emily | true. we could probably figure something out though. links or whatever. GHA can do custom buttons and stuff | 21:12:26 |
| emily | or the bot could just edit it in to your PR message | 21:12:36 |
| kuflierl | We also might want to have better linking. Something like a central file for all questions that branches out into the correct files | 21:13:15 |
| kuflierl | I always have issues finding something and rely on search engine foo | 21:13:39 |
| kuflierl | The answer tends to be "somewhere in the repo" | 21:14:31 |
 hexa | python-updates was mostly fine | 21:14:31 |
| hexa | one numpy 2.5.0 merge that didn't test jack shit is now causing all kinds of deprecationwarnings and api breakages | 21:14:59 |
| emily | I believe CONTRIBUTING.md actually links to all the other docs like pkgs/README.md? | 21:16:17 |
| emily | but yeah it's pretty confusing | 21:16:21 |
| hexa | I think it's just a lot to take in | 21:21:49 |
| emily | yeah, the ideal would be presenting the high-level principles and most important requirements upfront in a screen or two of text, with links to more detail | 21:25:56 |
| Grimmauld (any/all) | The people with whom i talked about starting out contributing mostly were willing to learn/read a lot, just intimidated by the amount of shit we have, scared to overlook something. Which, admittedly, it is quite easy to overlook something. When i review things, i try not to waste my or the reviewees time. Our documentation is currently NOT structured in a way that attempts to not waste time. Its dumped in random places, and even just getting an overview is a significant investment we expect new contributors to do. I don't think this is idea. | 21:26:22 |
| Grimmauld (any/all) | * The people with whom i talked about starting out contributing mostly were willing to learn/read a lot, just intimidated by the amount of shit we have, scared to overlook something. Which, admittedly, it is quite easy to overlook something. When i review things, i try not to waste my or the reviewees time. Our documentation is currently NOT structured in a way that attempts to not waste time. Its dumped in random places, and even just getting an overview is a significant investment we expect new contributors to do. I don't think this is ideal. | 21:26:26 |
| emily | can't avoid writing down specifics, but right now you have to wade through lots of tl;dr detail just to learn all the basic expectations about patching, commit messages etc. | 21:26:34 |
| Grimmauld (any/all) | And even then its a mess. I think we still don't have consensus about the fetchpatch2 situation... | 21:27:53 |
 Sapii/Saperson | maybe these can be moved up in the contrib.md so its the first thing seen? | 21:28:22 |
| emily | I think it's more like even with consensus we don't have people putting the effort into fixing things | 21:28:33 |
| Grimmauld (any/all) | if documentation were all in files, that'd be one thing. But sending newbies to years-ongoing technical discussions is bad | 21:28:33 |
| emily | myself included, it's just a rabbit hole I don't have time for | 21:28:45 |
| emily | and nobody owns our contributing docs really | 21:28:52 |
| Grimmauld (any/all) | sure | 21:29:01 |
| emily | it would be very high-value work if people wanted to improve them | 21:29:18 |
| Grimmauld (any/all) | everyones workflow is different. I have ideas how i would want contributing docs to be structured, but collecting all the things that need to be documented is tedious and making it work for everyone is basically impossible | 21:30:37 |
