ROOT version compatibily clarification

Dear ROOT team,

the versioning page of ROOT states for minor version changes that

Across minor versions ROOT guarantees source backward compatibility, i.e. “your source code will still compile”. You can expect that any breakage to existing code should be called out in the release notes, and it will most commonly be preceded by deprecation warnings.

But this seems contradicting in itself: does ROOT guarantee “source backward compatibility” across minor versions or not? The second sentence pretty clearly states that it does not (given a few conditions), while the first claims it does.

Should this be reformulated to something like “ROOT does not guarantee “source backward compatibility”, however, breaking changes to existing code should…”

Thanks for the clarification,

P.S: as guessed, this doesn’t come out of the blue and I do have examples that ROOT does indeed not keep “source backward compatibility” accross minor versions

Welcome to the ROOT Forum!
I’ll let @Axel comment on this.

Thanks! Can you let us know where we failed, please?

I’ll update the wording - the intent is to say that for user code incompatible changes (which, as explained, should not be happening between patch releases) these changes will me called out in release notes.


Thanks for the clarification!

which, as explained, should not be happening between patch releases

Yes, but the on the other hand

Across minor versions ROOT guarantees source backward compatibility , i.e

claims the same for minor versions, that’s the confusion

An example is the removal of tree.AsMatrix() that happened in 6.26. This was deprecated in 6.24 and removed, also announced in the analysis note.
But this means that it breaks backwards compatibility accross minor versions.

For the wording, I would then suggest to simply remove

Across minor versions ROOT guarantees source backward compatibility , i.e. “your source code will still compile”.

because its neither true nor the intent, if I understand things correctly?
Maybe it’s worth to write explicitly that “ROOT does not guarantee backwards compatibility accross minor version, but any breaking changes will be ”

Requirements are probably “deprecated at least one version before” and "explicitily listed in the changelog.

Ouch, thanks for pointing this out, that’s a bug: user code backward compatibility is guaranteed between patch releases, and for minor releases we call out breakage in the release notes. I.e. I think exactly as you worked out yourself. I’ll be back with a PR for the website!

Great, glad I could help, it’s too easy to overlook small typos in such a huge codebase.
Thanks for all the good work!

1 Like

I just proposed Fix incorrect wording of minor version backward compatibility by ferdymercury · Pull Request #940 · root-project/web · GitHub

1 Like

Across minor versions, ROOT strives to maintain source backward compatibility, meaning your source code should still compile. However, there may be exceptions where breaking changes are introduced. These changes will be documented in the release notes and are typically preceded by deprecation warnings.

@beredis thanks, I think this is also what was already discussed above.

However, there might be a slight misunderstanding in what “guarantee backwards compatibility” means:

there may be exceptions where breaking changes are introduced.

that is the very definition of not providing backwards compatibility. That’s fine. But there cannot be a guarantee that “no breaking changes are introduced” and “some breaking changes are introduced”, that’s exclusive.
The guarantee of backwards compatibility means that if upgrading from version X to Y breaks my code (and this isn’t because my code relied on a bug), then this is a bug in version Y that should be fixed.

The fact that things are deprecated etc doesn’t change that (that’s great, I would personally even expect that, but a breaking change is a breaking change).

Also, that most minor releases are compatible in most codebases and ROOT strives for that is good. As a sidenote, most libraries, AFAIK, do that; software isn’t expected to completely change in minor releases.

And again, it’s perfectly fine what ROOT does, it’s fine to not be fully backwards compatible in minor releases, in fact, this is what SemVer even suggests. But it should also be documented as that.