Why use poethepoet instead of devbox scripts?

[badrelmazaz]

Hey! 👋
First off, I really love how this project is structured, the dev environment setup with Devbox is super clean and makes it really easy to get started.
I noticed the project uses both Devbox for environment management and poethepoet for task running. I was curious: have you considered using the scripts section in devbox.json instead of poe?
Something like:

{ "shell": { "scripts": { "test": "pytest", "docs": "mkdocs serve", "lint": "pre-commit run --all-files" } } }

Then running tasks with devbox run test instead of poe test.
I know devbox scripts have some limitations compared to poe (no built-in help messages, less flexible argument handling, no direct Python function calls, etc.), so I'm guessing there's a good reason for the current setup. Just curious about the thinking behind it!
Thanks for maintaining such a great project.

[sisp]

Thanks for the praise! ❤️ I'm glad you like our DX! 🎉

We've been using Poe the Poet for quite a while, predating our adoption of Devbox. When migrating from pure Nix to Devbox, task management simply remained with Poe the Poet for no better reason than minimizing the migration effort. Thinking about it some more, although the Devbox dev environment is the preferred one, not all contributors may want to install Devbox, so Poe the Poet allows running some tasks that also work without a Devbox installation, e.g. poe test and poe lint (through Docker/Podman when no Devbox installation is found). Of course, our dev container integration avoids the need for a local Devbox installation as well, but I hear that not everybody likes dev containers. 🤷 If we migrate to Devbox scripts, we'll increase the need for contributors to install Devbox for a reasonable DX.

That said, I don't have strong feelings towards Poe the Poet. 😄

[badrelmazaz]

Thanks for the detailed explanation! That makes total sense regarding minimizing migration effort and keeping the barrier to entry low for contributors who might not want to install Devbox or use dev containers.

I admit I'm a huge fan of how Devbox centralizes everything, I usually try to slim down the toolchain as much as possible, but I definitely understand the need to support different workflows.

While we are on the topic of tooling, I had two quick suggestions/questions:

1. Pre-commit performance: Have you considered using prek instead of the standard pre-commit? It’s significantly faster and fully backward compatible with your existing config.
2. Linting: You might consider adding the S rule to ruff (flake8-bandit). It’s a great way to cover basic security checks without needing a separate tool.

Also, regarding your pre-commit config, I noticed you are using local hooks (installed in the project) rather than remote repos. Is that primarily to avoid version drift, or just to ensure the version matches the environment exactly every time?

[sisp]

Thanks for mentioning prek, I wasn't aware of it. I wonder how much overall speed-up there is, as I imagine the execution time is mostly given by the hooks and not the orchestration tool. Anyway, I'll definitely check it out!

Regarding Ruff rules: My personal preference is enabling all Ruff rules. 😄 But this works best for new projects; enabling all rules on an existing project in one step is often unmanageable. If you're interested, feel free to create PRs to enable more rules.

Regarding local hooks instead of remote repos: I know that pre-commit's official docs and the vast majority of projects use remote repos. But I think this is only a workaround for the lack of polyglot dependency management like Nix (via Devbox in our case). As you suspected, one concern of remote repos is version drift and consistency across the development lifecycle. pre-commit does not support dependency locking, so only the hook version is pinned while the dependency tree is resolved anew on every installation. This leads to non-reproducible hook installations. Also, many dev tools may be used in multiple places, e.g. linters/formatters/type-checkers may be run in an IDE like VS Code, they may be run in pre-commit hooks, and they may be run in CI. The behavior of these tools must be consistent wherever they are used. This means, either the tool installation must be perfectly reproducible, or the same executable must be used in all places. The former isn't possible with pre-commit, so we go for the latter. Also devenv's Git hooks feature uses only local hooks in the generated .pre-commit-config.yaml, using the tools installed via Nix.

[badrelmazaz]

Thanks for the insight! You are probably right that prek might not offer a huge speed-up if the hooks themselves are the bottleneck, but it's interesting nonetheless.

I also fully agree with your point on local hooks. Relying on the specific locked binaries via Nix is much safer than resolving the dependency tree on every install.

I'll take a look at the Ruff configuration and try to open a PR to incrementally enable some new rules to improve the developer experience.