Request: more tests, clearer migration guides & better highlighting of breaking changes

[scur-iolus]

First of all, thanks for maintaining this project. That said, I would like to raise a concern regarding the pace at which major changes seem to be introduced, often with very little warning and maybe not enough tests. In the last updates, it feels like significant or breaking changes are landing quickly, and it can be difficult for me, as a downstream user, to anticipate and to understand them.

In particular, migration guidance seems to be somewhat neglected. I do have noticed this migration guide to v4, but it seems to be a bit sparse (see for instance the numbering issue - there are two 1. -, note that dependencies like psutil and aio_pika are not mentioned, the "After" does not explain how to pass options to the checks - as a dict in a tuple -, etc.). When breaking or behavioral changes are introduced, having clear, precise, and detailed migration guides would make a huge difference for users like me integrating the library into production. Lately, upgrades have become risky and time-consuming.

Related to that, it would also help if the changelog highlighted breaking changes more prominently. For example, explicitly calling them out under a clearly marked Breaking changes section (and emphasizing them) would make it much easier to quickly assess the impact of an upgrade. In case of major upgrade, a link in the changelog to the migration guide would be welcomed.

Of course, I’m aware that I can mitigate this by pinning the dependency version in my pyproject.toml, which we already tend to do for safety. But that makes your efforts pointless, don't you think?

Thank you again for your work on the project, and for considering this feedback!

[codingjoe]

Dear @scur-iolus,

Thanks for the compliment. I agree this project has finally overcome its stagnant state.

As for the release process:

1. All releases follow SemVer versioning.
2. Breaking changes are usually announced via deprecation warnings.
3. v4 went through numerous pre-releases to ship a robust release.
4. You will find a change log in the documentation.

Regarding the more tests request: The test coverage was boosted from 60 to 100%, including the addition of integration tests against live services.

Of course, you can pin the V3 version, but it will no longer receive security patches. Please note that this project is maintained and developed by volunteering contributors. Should your company require support, I have a corporate sponsoring tier.

As mentioned in a previous response, I am more than happy to receive documentation patches. It's always challenging to write helpful documentation when you are overly familiar with the code base.

Kind regards,
Joe