calcite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Hyde <jh...@apache.org>
Subject Re: Breaking changes and internal APIs
Date Tue, 07 May 2019 18:25:12 GMT
Yes, we do follow semantic versioning. We are not dogmatic about it for a couple of reasons.

First, we don’t know which APIs are public. (In java you have to put the word “public”
on a lot of things, but that doesn’t make them public APIs.) We haven’t put the time and
effort into spelling out which APIs are public. 

We have a pragmatic definition of what is public: we take a good faith guess at what people
are using, we try not to break stuff, and if we are wrong, we rely on them to tell us.

So if Vladimir is writing to this list with breaking changes, I guess the process is working.

Second, we need to evolve. Sometimes we make mistakes in the design of our APIs, and we want
to make them better. Sometimes APIs just need to grow (e.g. adding support for the “FILTER
(WHERE …)” clause of aggregate functions affected the AggregateCall API). Usually we can
evolve APIs, but sometimes it is better to break/remove, and disclose in the release notes.
Or, keep things around, deprecated, for one minor release.

We have discussed this policy before[1][2], and I don’t think anyone was horrified by it.

I think the “Join, SemiJoin, Correlate” thread [3] was an excellent discussion, with many
participants chiming in, and it could not have been had if we were committed to never remove
anything.

Third, as a project we tend not to make major releases very often. Major releases are a big
part of semantic versioning (it’s the only point where you can make breaking changes to
APIs). But we’re capturing the spirit of it, which is to tell people, and give them notice,
before we change APIs. There are projects, such as Guava, which do follow semantic versioning
but still manage to piss people off more than we do.

Julian

[1] https://issues.apache.org/jira/browse/CALCITE-2969?focusedCommentId=16823296&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-16823296
<https://issues.apache.org/jira/browse/CALCITE-2969?focusedCommentId=16823296>

[2] https://lists.apache.org/thread.html/7ecec95ced1b3b3cf6728dfa2adfcf407fcc7049f83bdc36417ef904@%3Cdev.calcite.apache.org%3E
<https://lists.apache.org/thread.html/7ecec95ced1b3b3cf6728dfa2adfcf407fcc7049f83bdc36417ef904@%3Cdev.calcite.apache.org%3E>

[3] https://lists.apache.org/thread.html/41ed5806574e091ea2c7434fc2c90dac53036d7403092a63ee4a2173@%3Cdev.calcite.apache.org%3E
<https://lists.apache.org/thread.html/41ed5806574e091ea2c7434fc2c90dac53036d7403092a63ee4a2173@%3Cdev.calcite.apache.org%3E>


> On May 7, 2019, at 8:48 AM, Vladimir Sitnikov <sitnikov.vladimir@gmail.com> wrote:
> 
> Stamatis> While doing code-reviews there are times that I observe changes
> 
> Stamatis, thanks for raising the question.
> I was about to raise it (e.g. regarding join refactoring), however it is
> great the issue bothers more than just myself.
> 
> Calcite follows semantic versioning policy.
> 
> As you might know "C" in Calcite stands for consistency, so Calcite
> consistently sacrifices backward compatibility in favour of new features.
> 
> Apparently the only way to solve it is to setup some kind of automatic
> verification of API compatibility.
> The most simple things are "binary/source compatibility" (e.g. method
> renamed/removed), however there are more complicated things like "change in
> behavour" (e.g. method call sequence is altered)
> 
> The thing is Calcite can be used in 100500 ways, so no single
> "incompatible" change hits 100% of the users.
> For instance, "join refactoring" does defeat mat-calcite-plugin (e.g.
> https://github.com/vlsi/mat-calcite-plugin/blob/8c774d820859636c3921597eb0940295acbff191/MatCalcitePlugin/src/com/github/vlsi/mat/calcite/Query.java#L32
> ), however it is not like a showstopper.
> However, it is truly unamusing to have those breaking changes in "feature"
> releases like 1.20.
> 
> Vladimir


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message