I agree with Sean here. Interfaces with @Private annotations are going to be a problem. I think we should strongly discourage this. Either allow abstract classes are don't allow such things. We should have a note about this in the compatibility guide.
Even regarding the Util classes and the respective static methods - though we mark APIs private, if we change or remove those APIs still it will have compatability issues? We are following a practice of deprecating any API in such Util classes and removing them only in major APIs but the ones marked as @Private may be source of problem. Regards Ram On Tue, Aug 16, 2016 at 9:25 AM, Andrew Purtell <andrew.purt...@gmail.com> wrote: > > Are we extending this to all interfaces? Do we support folks > implementing their own Connection? Admin? > > This will bury us in weeds and bikeshedding. We can make a blanket rule > about source compatibility appropriately scoped to minors and/or patches > without that drama. To wit: > > > So when I read the existing guides, what I see is that we're supposed to > be _source_ compatible on minor and patch releases, but binary compatible > only on patch > > We should take the opportunity to clarify the language of the > compatibility guide. And if the above is the policy then the change to > Table is not allowed. > > > > On Aug 15, 2016, at 8:26 PM, Sean Busbey <bus...@apache.org> wrote: > > > > Thanks for bringing this up Josh! > > > > > > > > On Mon, Aug 15, 2016 at 2:21 PM, Andrew Purtell <apurt...@apache.org> > wrote: > > > >> > >> I find the InterfaceAudience annotations on this really strange. How can > >> we have a Public audience Interface (o.a.h.h.c.Table) with Private > methods? > >> > >> I'm also not sure the Private annotations on the Table interface are > that > >> useful. Any change to an interface renders it source incompatible, and > >> removal (or effective removal via signature change) of methods from an > >> interface introduces a binary incompatibility. I think the Private > >> annotations on methods of a Public interface imply we should refactor > those > >> methods to a non-public interface. > >> > > > > > > Generally, we use more restricted audience annotations on members within > a > > given API to show where there are limits on our support that we can't > > express in Java access modifiers. I think it's important for us to keep > > this around so that we can avoid a proliferation of "FooUtil" and other > > classes that exist just to make a Public/Private distinction. (I > recognize > > we have several of these but I was hoping we'd move in the direction of > > fewer over time.) > > > > I agree that in the case of interfaces it's problematic, since we have no > > way to distinguish between "should be consumed" and "can be extended". > > Perhaps we should make sure we have abstract classes instead of > interfaces? > > We could also add an annotation to make the consumed/extended > distinction; > > I've seen it come up a few times in other users of audience annotations. > > > > > > > >> > >> Now that we've had quite a few releases in the "not-quite-SemVer" > >> compatibility guide, is there any interest in trying to make the > >> compatibility guarantees more stringent? > >> > >> I was looking at our compat guidelines ( > >> http://hbase.apache.org/book.html#hbase.versioning) and think we could > >> make > >> a few refinements. > >> > >> We make several allowances for public interface changes that are binary > >> compatible but not source compatible in patch releases. I think we are > only > >> taking into consideration callers but should also consider implementors > of > >> public interfaces. Changing a public interface on a patch release > renders > >> it source incompatible. Can we avoid doing that on *patch* releases, and > >> restrict this type of change to minors? > > Are we extending this to all interfaces? Do we support folks implementing > > their own Connection? Admin? > > > > > >> Although we make allowances for public interface changes that are binary > >> compatible we also say "A minor upgrade requires no application/client > code > >> modification." which could imply source compatibility even across > minors, > >> which I believe is not the intent. > >> > >> We could add a source compatibility dimension for patch releases. > >> > >> > >> > >> I would like to see us get to source-compatibility on patch releases, > not > >> just binary compatibility > >> > >> You mean source compatibility for Public annotated interfaces only, > right? > >> > >> In that case evaluating compliance would be easy: RMs would run the API > >> compat checker on a RC and if a patch release the number of binary and > >> source compat issues should both be zero. > > So when I read the existing guides, what I see is that we're supposed to > be > > _source_ compatible on minor and patch releases, but binary compatible > only > > on patch releases. I think we discussed this a year or two ago, and IIRC > > the reasoning was that since we maintain wire compatibility on minor and > > patch releases, those who need to ignore a given set of binary > incompatible > > changes can just make use of the older library. >
