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 Wed, 08 May 2019 17:29:20 GMT
+1

> On May 8, 2019, at 6:17 AM, Stamatis Zampetakis <zabetak@gmail.com> wrote:
> 
> To summarize what Julian said (and to be sure I understood well), if the
> committer who is doing the review considers that the classes affected by
> the changes are not public API there is no need to:
> * deprecate first and remove later the respective classes/methods;
> * provide further notice to clients through the release note.
> 
> For the future, I think it will be useful to make an effort to annotate
> public APIs accordingly. It could give more flexibility to developers and
> also speed-up reviews. It will also facilitate the task of end-users who
> will be exposed to fewer classes and interfaces. I guess binary/source
> compatibility would also be easier to perform.
> However, I agree it is not an easy task so let's not try to solve it in
> this discussion.
> 
> 
> On Tue, May 7, 2019 at 8:25 PM Julian Hyde <jhyde@apache.org <mailto:jhyde@apache.org>>
wrote:
> 
>> 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 <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>
>> <
>> 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>
>> <
>> 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