Road to v1.0

[gabrieldemarmiesse]

Hi all,

So we spend quite some time (3+ years) with python-on-whales v0.x. It allowed us to make breaking changes, experiment, etc...

I gathered some numbers:

• 450 stars
• 370K downloads per month
• 52 contributors
• 2 maintainers (thanks so much @LewisGaul for everything)
• 2 clients tested (docker and podman)

First of all, thanks for everyone who opened pull requests and issues, that's awesome and the project wouldn't be there without you :)

We're not a small project anymore that can affort breaking changes left and right, and we need to also give some garantees to our users.
I say we're not a small project, but we have a small codebase, and I'd like to keep it that way, so that we can have an easy maintenance.

It's time to a v1.0. And this issue is here to list what are my thoughts, what should be done beforehand and during the transition.
We want to minimize the number of changes in v1.0 (I don't want to do what pydantic did when upgrading to v2), we'll target more what sqlalchemy did for v2, meaning most of the changes and apis are available before the major version upgrade.

What we should do before v1.0:

Stabilizing the API to avoid future breaking changes:

• Consider adding subcommand aliases #537
• Make typer/tqdm/requests optional dependencies? #512 (at least add the warnings)
• Force some arguments to be only positional and some arguments to be passed only by keyword. #495
• top is aliased incorrectly #450
• Drop support for python 3.7 #409 (use typing.TypedDict and typing.Literal), we can open another issue to track this
• Give somewhere the list of garantees that we, as maintainers of the project, provide. Something along the lines of "we garantee code reviews, answering issues and security fixes in a timely manner, everything else is up to the community. We follow semver, here is how we interpret it... and here is how to know if some function/class/attribute belongs to the public API"
• Use python's conventions to make certain modules/functions/attributes privates.

Making it easy to contribute to the project and fix bugs:

• Adding pyupgrade to the pre-commit #539
• Use UV as our main way of doing the project setup
• Support cleanly multiple clients in the tests #542

What we should do when setting the version to 1.0:

• Make typer/tqdm/requests optional dependencies? #512 (drop completely the CLI interface and auto-download)

We should open issues to track the items in this list without issues and also make a milestone in github for easier tracking of the progress.

Timeline

I want to be clear that there is no timeline for the v1.0. The open-source world is slow and stress-free (most of the time) and I'd like to keep it that way. We're all unpaid volunteers here. Contributing should be fun, and we should strive for high quality code. For this, we won't compromize on any timeline. If you're in a hurry, fork the project :p .

Thanks again for everyone who helped so far, and thanks in advance for everyone who will help us get to the 1.0 :)