Repo Health Questions [to maintainers]

[anchildress1]

Hey @localden @jflam. I know you guys stay busy (as do I!), so I had a couple ideas that I'm willing to help put together just to keep things organized and wanted your thoughts before actually touching anything. I appreciate wanting to keep the project as simple as possible, but there's a few small things that could make a big difference.

1. There's currently 452 open issues which honestly hurts my head to think about much. What do you think about these couple of automations to help?

   • Set the repo auto-close to true when a PR is merged that references an issue. I don't have the ability to close them, but I know there's at least a few doc-specific ones that can be closed. If that box is checked, you don't have to worry about it. Is this possible?

   • I can set up a weekly workflow to take care of the stale PRs and issues using https://github.com/actions/stale. It doesn't have to be strict by any means—the default 60 days without an update is probably too much right now! Also, little things like exempt if assigned or isDraft plus any specific labels you want will help some, too. It doesn't appear to support any sort of maximum count currently, though, so we'd need to either start closing newer ones first (less than ideal) or just be prepared for the initial onslaught. 🤷🏻‍♀️

2. I mostly started updating the docs cause I was taking apart the repo anyway to see exactly how it works, but these are behind—a lot—and there's no possible way to get caught up any time soon given the speed I can currently contribute. So here's a few options that could help:

   • I can create an agentic workflow to automate most of this. Copilot is really the one writing them anyway and I've got some pretty good instructions that I can repurpose, so it shouldn't be too hard to keep Copilot in line. Plus, I'd limit PRs to exactly one doc at a time and maybe set up a config or input of some kind—at least at first—to help direct. The beautiful part is that after catch-up is finished, the docs would theoretically handle themselves with a couple targeted adjustments. 😃

   • If we want to stay away from the highly experimental workflows, I can alternatively wire up a custom workflow that uses coding agent instead. I've yet to personally test the automation piece despite it being mostly written already, but the general flow I use manually at work all the time. It would need a bit of tweaking for this purpose, but nothing outrageous. This option would be really nice to enlist volunteers to use their Copilot requests instead of mine, too! We'd need to talk through how that could work, though.

   • Else, I don't mind to keep doing them manually as I find time, but a python formatter and lefthook config in the repo would help a lot with that. I know the markdownlint-cli is configured already, but I don't want to keep up with a new CLI if I don't have to, especially when uvx can accomplish the exact same functionality. I have a couple specific libraries to pick from if automation isn't possible. If I'm going to set this up though then we might as well throw in ruff, too, at a minimum.

3. Last, regarding this __init__.py situation... Exactly why did we choose to put 1.3k lines of code in that one file versus, well... literally any other approach? Are there any objections to a little refactoring here to at least split the functionality out into a few logical groups?

   • What about testing? I can scaffold a quick baseline suite and add unit testing as the code gets moved around to make sure everything still works after the fact. Anything wrong with the standard pytest + pytest-cov setup? What's the baseline coverage goal? I usually set mine at 80% as the baseline and adjust from there.

Let me know where you want to go with this and I'll see what I can do about making it happen!