Christmas-Wish: Backwards Compatibility

[Linafri]

Hello,

I see that alone this year there were many breaking changes in Minor versions (X in 3.X.*).
And in my view, this could have been handled better: e.g. the naming of slave vs. device:
Why not allow both notions until the next Major version?

def __init__(self, **kwargs):
    self.slave = kwargs.pop('slave', kwargs.pop('unit', 1))
    if 'unit' in kwargs:
        warnings.warn("'unit' is deprecated, use 'slave'", DeprecationWarning)

Next example:
In version 3.8.0, many constructors (like ModbusTcpClient) stopped accepting positional arguments.
ModbusTcpClient("127.0.0.1", 502) suddenly threw a TypeError. You were forced to write host="127.0.0.1", port=502.

Better approach: Graceful Degradation. Use *args to capture positional arguments, mapped them to the correct attributes, and issued a FutureWarning.

Or:
The way SSL/TLS is handled was completely restructured, moving away from simple parameters (certfile, keyfile) to a more complex sslcontext approach. Also here, backwards-compatibility would have been possible until next major version.
and/or a helper method that automatically constructs the new SSLContext if the old parameters were detected. This would allow the underlying engine to be modern while keeping the entry point user-friendly for legacy users.

Or:
Pymodbus frequently reorganizes its internal folder structure (e.g., moving things from pymodbus.client.sync to pymodbus.client).

The problem is: it is not always possible to use a specific pymodbus-version for the own Software.

May I ask you to consider such backwards-compatibility?

Greetings,
Hendrik

[janiversen]

May I suggest you read our README.rst, What you basically ask for is semver compatibility, something we have decided not to do.

Think about it, it really would not change anything except instead of having v3.11.z you would have something like v92.0.0, the schedules would be unchanged.

The bad thing about semver is that you cannot see if a bump was due to a major change or just a minor edit.

This year we have done a major rewrite of especially the async client, and to help users we have tried to make smaller releases easy to adapt, if you do not like that then wait with upgrades.

We reorganice our internal structure as we please, since it is not part of the API it cannot disturb you.

[janiversen]

A lot of your sugestions make sense, and could be easily done, however that requieres people like you to be active and write code to make it happen, just wishing does not make it happen.

[henfri]

TL;DR:
My main concern is dependency hell in plugin-based architectures, where frequent minor breaking changes make "just updating" impossible without breaking the ecosystem. I am strictly arguing for deprecation cycles (warn first, break later) and aliasing to ensure stability.
Note: If your mind is firmly set on the current strategy, please feel free to disregard (and close) this. I do not intend to start a debate, but simply want to provide feedback from a downstream integrator's perspective to be helpful.

---

Hello,

Thanks for the reply and the open discussion.

I actually fully agree with your critique regarding SemVer:

The bad thing about semver is that you cannot see if a bump was due to a major change or just a minor edit.

You are absolutely right. SemVer has a granularity problem: A Major bump acts like a "black box"—it fails to communicate whether the user faces a complete rewrite or just a single renamed parameter. It doesn't reflect the magnitude of the migration effort.

However, while SemVer fails to signal the volume of work, it is currently our only standard to signal compatibility. Disregarding it creates a severe problem for downstream integrators:

The Real Issue: Dependency Hell in Plugin Architectures
I work on a product that supports an ecosystem of many plugins/integrations (similar to Home Assistant). Some are maintained actively, others are not. They all rely on pymodbus.

When breaking changes occur in Minor releases (e.g., 3.7 -> 3.8):

1. Plugin A updates to 3.8 to fix a bug.
2. Plugin B (which hasn't been updated yet) crashes because it relies on an API that was renamed/removed in 3.8.
3. We cannot comfortably install two different versions of pymodbus in the same environment.

This creates an unresolvable "Dependency Hell" for us.

Regarding "Resources" and Priorities:

however that requieres people like you to be active and write code to make it happen

I understand that resources are scarce. However, preserving backward compatibility (e.g., via aliases) often takes less effort than managing the fallout of breaking changes.
Adding a simple mapping line like self.slave = kwargs.pop('unit') takes minutes. Dealing with the resulting issues in thousands of downstream installations, answering GitHub issues, and forcing every plugin developer to refactor takes hours collectively.
It is a question of priorities: Is "clean code" currently more important than "ecosystem stability"?

Regarding "Avoidable Churn" (Back-and-Forth Changes):
You asked for examples where fewer iterations would have saved work.

1. The Naming Carousel (unit slave device_id):
   in response to
   Think about it, it really would not change anything except instead of having v3.11.z you would have something like v92.0.0, the schedules would be unchanged.
   Integrators have been forced to rename the exact same parameter multiple times. First, we were told to move from unit to slave. Just as we adapted, v3.10 replaced slave with device_id.
   This is a prime example of churn. A stable API design would have picked one term and stuck with it for the major version lifecycle, or supported aliases for much longer.
2. The Revert (v3.10 v3.11):
   v3.10 changed the bit handling order (LSB MSB). v3.11 reverted this change because it was considered wrong. Users who updated diligently to v3.10 had to change their logic, only to revert it again for v3.11.

Regarding "Internal Structure":

We reorganice our internal structure as we please, since it is not part of the API it cannot disturb you.

You are likely referring to my example of imports moving from pymodbus.client.sync to pymodbus.client.
The problem is clarity. In Python, unless a module is explicitly private (prefixed with _), the file structure often becomes the de-facto API, especially if documentation or IDE autocompletion leads us there.

If you move a class (e.g., from path.A to path.B), please leave a "stub" in path.A that imports path.B and emits a DeprecationWarning. Simply deleting path.A causes immediate crashes (ImportError) and is very hostile to the ecosystem.

My Request / Proposal:
I do not mind if the version number jumps to v92.0.0. But I strictly need predictability to keep the ecosystem alive.

1. Deprecation Cycles: Please don't remove features immediately. Mark them as deprecated (emitting a FutureWarning) in version X.Y and remove them in X.Y+1.
2. Graceful Degradation: Mapping old arguments (like unit) to new attributes internally for one cycle would save us hours of debugging.

This would help mitigate the "bad thing about semver" significantly, as it gives us time to adapt, regardless of the version number.

Thanks for your time and consideration.

Best regards,
Hendrik

[janiversen]

Just a few comment.

I think you partly misunderstood my comment on semver. My point was that it would not change the release schedules just the numbering, so it really should not make a change to you.

Our version definion (which are used in many projects) do like semver tell exactly when there are changes or not !

You can argue that keeping backward compatibility is costung less than solving the reasulting issues.....that is not always true, you pointed at a change we made to avoid having continued issues. I refer to the change where we disallowed giving positional arguments for keyword parameters, doing that is bad style, but did not stop people from complaining.

We actually document what is considered API, if people use other parts that is their problem, and it is likely not to work with any upgrade.

At the end of the day, like with any FOSS projects it is the doers who make the direction of the project....and most fixes we merge (remember this project have a nice share of non-maintainer commits) do not care a lot about compatibility.

But since you care, I suggest you start getting active and become our compatibility guard.

[janiversen]

#2836 is not what you wished for, but it solved the basic problem I know well from Homeassistant in an elegant way, by providing a simple way to "isolate" different pymodbus instances.

[henfri]

Thanks a lot, I appreciate that. It helps a lot.

Notwithstanding that, I think that you could do a bit more to avoid that this workaround needs to be done with not too much effort. I would appreciate if you consider that.

[janiversen]

I could probably do more than "a bit more", but that is not how open source works !

Asking others to do what you want is something you can do with a paid for product, in FOSS the saying goes "If you have an itch, scratch it", and my itch is to ensure a working and efficient library.

So again if you want influence, start helping.

[henfri]

I understand. However, I would like to offer a different perspective on this statement:

Asking others to do what you want is something you can do with a paid for product... So again if you want influence, start helping.

I respectfully disagree with the definition that "helping" or "contribution" in FOSS is limited to writing code / PRs.

Feedback is Contribution. In my experience with other Open Source projects (e.g., SmartVisu, SmarthomeNG), maintainers explicitly valued architectural feedback, use-case analysis, and "stress-testing" concepts purely through discussion. I never wrote a line of code for them, yet my input helped shape the software to be more usable and robust - and the main authors explicitly valued that.

"Writing code" is solving the "How". What I am offering here—by highlighting the dependency hell, the API churn, and the ecosystem impact—is the "What" and the "Why". Ignoring the downstream impact of changes leads to software that is technically "clean" but practically difficult to integrate. Pointing this out is a contribution, as it prevents the library from designing itself into an isolated corner.

my itch is to ensure a working and efficient library.

That is exactly where our goals align. But I argue that a library is only truly "efficient" if it respects the time of those who use it. If a library saves 10ms of CPU time but costs the developer community 1000 hours of refactoring due to broken APIs, the total efficiency of the system is negative.

TL;DR: I am not asking you to work for me. I am scratching my itch (ecosystem stability) by providing the "User Perspective" that you, as the deep-dive developer, might naturally overlook.

Whether you accept this type of contribution is, of course, your decision. I will leave it at that. Thanks for the discussion.

[janiversen]

I do accept that contribution are part of FOSS, and actually we get quite a lot of input that way, however I was merely informing you that we do not have bandwidth to be observant of such corner cases without help.

To be honest I only know of 2 projects that have a "dependency hell", yours and homeassistant (which solved it rather drastically), the rest of our user base do not seem to have this particular problem.