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 <[email protected]> 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 < > [email protected]> 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 > >
