Repository navigation
Definition of backwards-compatibile for Modelica libraries #3209
Description
Modelica library developers are converting their libraries to MSL 4.0.0, after almost 10 years of backwards-compatible MSL, when nobody bothered. This raises one fundamental question: what does backwards compatible actually mean for Modelica libraries?
Based on some discussion on modelica-design, there are two possible definitions
- Weak backwards compatibility: library MyLib v.x is backwards-compatible with library MyLib v.y if there is no need of a conversion script specific to library MyLib to convert existing libraries that use MyLib v.x to use MyLib v.y. In other words, there is no need to change how you define or instantiate classes of MyLib in your models between v.x and v.y.
- Strong backwards compatibility library MyLib v.x is backwards compatible with MyLib v.y if there is no need of any conversion script whatsoever to convert existing libraries that use MyLib v.x to use MyLib v.y. In other words there is no need to change anything in your models to use MyLib v.y instead of MyLib v.x
Based on what I see in https://github.com/modelica-3rdparty, there are many libraries which have been converted to MSL 4.0.0, withouth changing their own interfaces (so no conversion script needed), _except for the MSL uses annotation, which requires to run the conversion script of MSL 4.0.0 on your own model. Some of then are adopting the weak definition, so they bump a minor release number, while others adopt the strong definition and they bump the major release number.
It would be good if we could reach some consensus of the community on what is the preferred interpretation, even though this might be too late already for the majority of MSL 3.2.3 -> 4.0.0 conversions. At least we'd be ready for the next MSL 5.0.0 in 10 years from now, and we would help getting package managers into the mainstream with shared conventions among tools.
The outcome of this discussion should eventually become part of MCP-0016.
Activity
dietmarw commentedon Jun 22, 2022
@casella using your "v.x" and "v.y" notation makes it difficult to identify what you are trying to describe (especially since I think you got a typo in the strong backward compatibility). As a first step when discussing this, one needs to agree to start by using semver in order to make any statement of the definitions. Libraries that have not used it so far should implement it with the next release and can then decide on the compatibility.
Example:
Let's say that MyLib has not been following semver so far and had a version
5.3which uses MSL 3.2.3.5.4.0or6.0.0. The meaning would be the following:5.4.0(uses MSL3.2.3): User models using5.3can use5.4.0without any conversion.5.4.0(uses MSL4.0.0): In case none of the classes inside MyLib are impacted by the conversion to MSL 4.0.0 one could make the case that this is a backwards-compatible version with no conversion of the MyLib components (!) used in the UserLib. However, since MyLib now uses (and loads) MSL 4.0.0 the tool would trigger the conversion script of the MSL to 4.0.0 which might do changes to UserLib (we said that MyLib did not have any changes that affect UserLib)6.0.0(uses MSL4.0.0):X.Y.Zdefinition.6.0.0(uses MSL3.2.3) would of course also be possible due to non-backwards changes in MyLib with still the same MSL 3.2.3 dependency, but this is not the focus here)dietmarw commentedon Jun 22, 2022
One case I forgot:
5.3.1(uses MSL 3.2.3): Should the developers decide on a new bugfix release without any new features and changes to the libraries used then they can adopt semver right away. But should then state that no conversion is needed.casella commentedon Jun 22, 2022
Sorry, what I meant with v.x is some version (e.g. version 5.2.3) and v.y is some other version (e.g. version 5.3.1, or 6.0.0-beta.1). The only thing that matters is that they are different.
I think I now corrected that, thanks! 😅
I agree we should all use semver and propose an orderly path to migrate to that, but that's beyond the scope of this discussion. Ockham's razor here. I would just like to get a consensus on a single issue in this ticket: what do we mean as backwards compatible, which then will have obvious consequences on semver version numbers, that we need not discuss here. Hence, again, I'm using v.x and v.y and not getting into the intricacies of semver numbering, because they are not relevant to the discussion.
To summarize even further, the question is the following:
As I understand from your previous comment, your answer to this question is YES, hence you suggest to switch to 6.0.0 if using semver, just to point out to the user that there is no way back, even if there is no need to run MyLib-specific conversion scripts, only MSL 4.0.0 conversions.
I understand that also @GallLeo shared this opinion, on the ground that it should be clear to the end user that something irreversible happens to UserLib if it switches to this new version.
It was also shared by @sjoelund on the grounds that the set of used libraries is integral part of the interface of MyLib.
dietmarw commentedon Jun 22, 2022
@casella This is where I think you have a typo:
casella commentedon Jun 22, 2022
OMG, sometimes I'm really dumb 😄. That's fixed now.
henrikt-ma commentedon Jun 23, 2022
I also agree that this must be considered a backwards incompatible change. It makes good sense to me that a library author who is wary about introducing backwards incompatible changes needs to think carefully before changing library dependencies in a backwards incompatible way.
In the future, there could be ways of saying that there are multiple (major) versions of a used library that all work with the authored library, and this would then open up for sometimes being able to allow a new major version of a used library as an alternative to the old version, without the need to consider this a backwards incompatible change in the authored library.
casella commentedon Jun 23, 2022
Good to see some consensus building up, it would be good to have other opinions, e.g. @mtiller, @MartinOtter, @beutlich, @AHaumer.
HansOlsson commentedon Jun 23, 2022
To me focusing solely on changes caused by conversions of other libraries seems a bit odd; and I believe we first need to establish what we mean with compatibility of the library itself - and then this follow automatically.
So for versioning in general the practical problems are in terms of priority (most impacting at the top):
Only 6 is real backward compatibility, and in practice almost every release is at 4 or lower - and thus users need to verify that it is compatible. Claiming otherwise will only be seen as attempting to trick our users.
For conversion in general and convertMessage in particular we see that we need a more refined concept than whether MSL 4.0.0 is backwards compatible with MSL 3.2.3, since it depends on what features of MSL 3.2.3 were used, and we can actually check that.
henrikt-ma commentedon Jun 23, 2022
I think that conversions is just one example of something that would require the new version of the used library to be considered non-backwards compatible with its previous version. The discussion we're having here is meaningful without knowing exactly what is meant by "backwards incompatible"; if the dependency library has determined that its new version isn't a backwards compatible release for one reason or another, could the dependent library change its
usesannotation to require the new version without it being considered a backwards incompatible change?To me, this seems like something that shouldn't be left to the author of the dependent library to decide. In other words, I see such a change of library dependency as one of the things that should be on our list of changes that definitely requires bumping the major version.
casella commentedon Jun 23, 2022
This is really too strict. If you really want this kind of backward compatibility, then you have to stick to the same version forever. I guess it is well understood that if you upgrade to a newer version of a library you may get different results, hopefully more accurate, robust, fast, or whatever. That (together with getting new models) is the whole point of upgrading to a new version of a library
Sure, I guess everybody understands that. The question is: "can I compile the model or not?". Maybe for the purposes of this discussion we could stick to that as definition of backwards compatibility.
Sorry, I don't get this. MSL 4.0.0 as whole is not backwards compatible with MSL 3.2.3. Of course if you don't use SI units you may have models using MSL 3.2.3 that can actually also run with MSL 4.0.0 without any change, but that doesn't make MSL 4.0.0 backwards compatible with MSL 3.2.3.
If at some point I decide do migrate a certain user library to MSL 4.0.0, I need to migrate all its dependencies to it as well. Counting on the fact that the specific models I'm using and all their dependencies can work without any conversions (by sheer luck) doesn't seem to me something that I should rely upon. BTW, I could add some more models to my user library that require new features of MSL 4.0.0 that are not backwards-compatible, and getting an error only then would be a bit odd.
HansOlsson commentedon Jun 27, 2022
Yes, the point is that there are trade-offs.
That's sort of the relevant question (with the caveat - will it give about the same result?) - but it is depends on the model as seen below.
True, but what is more interesting case is that if your library uses MSL 3.2.3 it is not guaranteed that it can be automatically converted to MSL 4.0.0.
If you used a few specific models (tests and internal models) e.g.,
Modelica.Fluid.Fittings.BaseClasses.QuadraticTurbulent.TestWallFrictionthe automatic conversion didn't work (well, it generated a message saying that it didn't). I assume no-one used them so they don't care - so we shouldn't be afraid to remove them; and similarly correcting the behavior even if that strictly breaks some models.casella commentedon Jun 27, 2022
When we decided to start MSL 4.0.0, the agreement was that we were OK with it under the assumption that automatic conversion would always work.
If there are some exception to this rule regarding some test models, I would not to be worried; I don't think this is enough cause to say that we don't have automatic conversions.
This has already been the case in the past with MSL 3.2.x backwards compatibility - there were a few exceptions, but as long as they were clearly documented, it was ok to declare newer versions as backwards compatible.
Apparently, package management is not an exact science 😄
HansOlsson commentedon Mar 26, 2026
See also the proposed version compatibility for MSL in modelica/ModelicaStandardLibrary#4698