I cross-posted my reply, so this thread is on both lists now. On Fri, Mar 30, 2018 at 3:32 PM, Jihoon Son <ghoon...@gmail.com> wrote:
> Thanks. > > Should I send this email to the Apache mailing list as well? > > Jihoon > > 2018년 3월 30일 (금) 오후 1:58, Gian Merlino <g...@imply.io>님이 작성: > > > Hi Jihoon, > > > > The javadoc for @PublicApi explains the intent. They can change, but not > > in a minor release. There should also > > be some consensus around changing them. Once we are 1.0, then we should > > only change PublicApis when going > > to 2.0. > > > > Btw, since we are trying to migrate the dev mailing list to Apache, > please > > cross post this sort of thing with > > d...@druid.incubator.apache.org, or even only post to that list. > > > > From the javadoc: > > > > > Signifies that the annotated entity is a public API for extension > > authors. Public APIs may change in breaking ways > > > only between major Druid release lines (e.g. 0.10.x -> 0.11.0), but > > otherwise must remain stable. Public APIs may > > > change at any time in non-breaking ways, however, such as by adding new > > fields, methods, or constructors. > > > > > > Note that interfaces annotated with {@code PublicApi} but not with > > {@link ExtensionPoint} are not meant to be > > > subclassed in extensions. In this case, the annotation simply signifies > > that the interface is stable for callers. > > > In particular, since it is not meant to be subclassed, new non-default > > methods may be added to an interface and > > > new abstract methods may be added to a class. > > > > > > If a class or interface is annotated, then all public and protected > > fields, methods, and constructors that class > > > or interface are considered stable in this sense. If a class is not > > annotated, but an individual field, method, or > > > constructor is annotated, then only that particular field, method, or > > constructor is considered a public API. > > > > > > Classes, fields, method, and constructors _not_ annotated with {@code > > @PublicApi} may be modified or removed > > > in any Druid release, unless they are annotated with {@link > > ExtensionPoint} (which implies they are a public API > > > as well). > > > > Gian > > > > On Thu, Mar 29, 2018 at 5:45 PM, Jihoon Son <jihoon...@apache.org> > wrote: > > > >> Hi folks, > >> > >> I wonder what's the exact meaning of the 'PublicApi' annotation. From > >> https://github.com/druid-io/druid/pull/4433, > >> > >> > @PublicApi which signifies something you're not meant to subclass, but > >> that you can use for implementation. > >> > >> I can also see some methods can't be deleted because they are in some > >> classes annotated with @PublicApi. Here is an example in TaskRunner. > >> > >> /** > >> * Start the state of the runner. > >> * > >> * This method is unused, but TaskRunner is {@link PublicApi}, so we > >> cannot remove it. > >> */ > >> @SuppressWarnings("unused") > >> void start(); > >> > >> Does this mean @PublicApi classes must change in a backward-compatible > >> way? Or can we change in a non-compatible way and call out when we > release? > >> > >> If this is not defined yet, it would be good to start a discussion on > >> this. > >> > >> Best, > >> Jihoon > >> > >> -- > >> You received this message because you are subscribed to the Google > Groups > >> "Druid Development" group. > >> To unsubscribe from this group and stop receiving emails from it, send > an > >> email to druid-development+unsubscr...@googlegroups.com. > >> To post to this group, send email to druid-developm...@googlegroups.com > . > >> To view this discussion on the web visit > >> https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG- > 6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com > >> <https://groups.google.com/d/msgid/druid-development/CACZfFK4_xEG- > 6JSdqARh3SRRVWCgoSVpK3Z48rqUhOTuqS-x3w%40mail.gmail.com?utm_ > medium=email&utm_source=footer> > >> . > >> For more options, visit https://groups.google.com/d/optout. > >> > > -- > > You received this message because you are subscribed to the Google Groups > > "Druid Development" group. > > To unsubscribe from this group and stop receiving emails from it, send an > > email to druid-development+unsubscr...@googlegroups.com. > > To post to this group, send email to druid-developm...@googlegroups.com. > > To view this discussion on the web visit > > https://groups.google.com/d/msgid/druid-development/ > CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail.gmail.com > > <https://groups.google.com/d/msgid/druid-development/ > CACZNdYAPj7o4DF3AekgM1Bv77gQV5f6JWikknjtZM5x4QtT2ng%40mail. > gmail.com?utm_medium=email&utm_source=footer> > > . > > For more options, visit https://groups.google.com/d/optout. > > >