calcite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stamatis Zampetakis <zabe...@gmail.com>
Subject Re: Breaking changes and internal APIs
Date Wed, 08 May 2019 13:17:50 GMT
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> 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
> >
>
> [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