Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
Thanks everyone for chiming in. I created https://issues.apache.org/jira/browse/HADOOP-10896 as a 2.5 blocker. On Thu, Jul 24, 2014 at 9:34 PM, Chris Nauroth cnaur...@hortonworks.com wrote: +1 for the proposal. I believe stating that classes without annotations are implicitly private is consistent with what we publish for our JavaDocs. IncludePublicAnnotationsStandardDoclet, used in the root pom.xml, filters out classes that don't explicitly have the Public annotation. Chris Nauroth Hortonworks http://hortonworks.com/ On Wed, Jul 23, 2014 at 10:55 AM, Karthik Kambatla ka...@cloudera.com wrote: Fair points, Jason. The fact that we include this in the compatibility guideline should not affect how developers go about this. We should still strive to annotate every new class we add, and reviewers should continue to check for them. However, in case we miss annotations, we won't be burdened to support those APIs for essentially eternity. I am aware of downstream projects that use @Private APIs, but I have also seen that improve in the recent past with compatible 2.x releases. So, I am hoping they will let us know of APIs they would like to see and eventually use only Public-Stable APIs. On Wed, Jul 23, 2014 at 7:22 AM, Jason Lowe jl...@yahoo-inc.com.invalid wrote: I think that's a reasonable proposal as long as we understand it changes the burden from finding all the things that should be marked @Private to finding all the things that should be marked @Public. As Tom Graves pointed out in an earlier discussion about @LimitedPrivate, it may be impossible to do a straightforward task and use only interfaces marked @Public. If users can't do basic things without straying from @Public interfaces then tons of code can break if we assume it's always fair game to change anything not marked @Public. The well you shouldn't have used a non-@Public interface argument is not very useful in that context. So as long as we're good about making sure officially supported features have corresponding @Public interfaces to wield them then I agree it will be easier to track those rather than track all the classes that should be @Private. Hopefully if users understand that's how things work they'll help file JIRAs for interfaces that need to be @Public to get their work done. Jason On 07/22/2014 04:54 PM, Karthik Kambatla wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik -- CONFIDENTIALITY NOTICE NOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
+1. Colin On Tue, Jul 22, 2014 at 2:54 PM, Karthik Kambatla ka...@cloudera.com wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
+1 for the proposal. I believe stating that classes without annotations are implicitly private is consistent with what we publish for our JavaDocs. IncludePublicAnnotationsStandardDoclet, used in the root pom.xml, filters out classes that don't explicitly have the Public annotation. Chris Nauroth Hortonworks http://hortonworks.com/ On Wed, Jul 23, 2014 at 10:55 AM, Karthik Kambatla ka...@cloudera.com wrote: Fair points, Jason. The fact that we include this in the compatibility guideline should not affect how developers go about this. We should still strive to annotate every new class we add, and reviewers should continue to check for them. However, in case we miss annotations, we won't be burdened to support those APIs for essentially eternity. I am aware of downstream projects that use @Private APIs, but I have also seen that improve in the recent past with compatible 2.x releases. So, I am hoping they will let us know of APIs they would like to see and eventually use only Public-Stable APIs. On Wed, Jul 23, 2014 at 7:22 AM, Jason Lowe jl...@yahoo-inc.com.invalid wrote: I think that's a reasonable proposal as long as we understand it changes the burden from finding all the things that should be marked @Private to finding all the things that should be marked @Public. As Tom Graves pointed out in an earlier discussion about @LimitedPrivate, it may be impossible to do a straightforward task and use only interfaces marked @Public. If users can't do basic things without straying from @Public interfaces then tons of code can break if we assume it's always fair game to change anything not marked @Public. The well you shouldn't have used a non-@Public interface argument is not very useful in that context. So as long as we're good about making sure officially supported features have corresponding @Public interfaces to wield them then I agree it will be easier to track those rather than track all the classes that should be @Private. Hopefully if users understand that's how things work they'll help file JIRAs for interfaces that need to be @Public to get their work done. Jason On 07/22/2014 04:54 PM, Karthik Kambatla wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik -- CONFIDENTIALITY NOTICE NOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
+1 for Karthik's suggestion. - Tsuyoshi On Wed, Jul 23, 2014 at 6:54 AM, Karthik Kambatla ka...@cloudera.com wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik -- - Tsuyoshi
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
I think that's a reasonable proposal as long as we understand it changes the burden from finding all the things that should be marked @Private to finding all the things that should be marked @Public. As Tom Graves pointed out in an earlier discussion about @LimitedPrivate, it may be impossible to do a straightforward task and use only interfaces marked @Public. If users can't do basic things without straying from @Public interfaces then tons of code can break if we assume it's always fair game to change anything not marked @Public. The well you shouldn't have used a non-@Public interface argument is not very useful in that context. So as long as we're good about making sure officially supported features have corresponding @Public interfaces to wield them then I agree it will be easier to track those rather than track all the classes that should be @Private. Hopefully if users understand that's how things work they'll help file JIRAs for interfaces that need to be @Public to get their work done. Jason On 07/22/2014 04:54 PM, Karthik Kambatla wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
Fair points, Jason. The fact that we include this in the compatibility guideline should not affect how developers go about this. We should still strive to annotate every new class we add, and reviewers should continue to check for them. However, in case we miss annotations, we won't be burdened to support those APIs for essentially eternity. I am aware of downstream projects that use @Private APIs, but I have also seen that improve in the recent past with compatible 2.x releases. So, I am hoping they will let us know of APIs they would like to see and eventually use only Public-Stable APIs. On Wed, Jul 23, 2014 at 7:22 AM, Jason Lowe jl...@yahoo-inc.com.invalid wrote: I think that's a reasonable proposal as long as we understand it changes the burden from finding all the things that should be marked @Private to finding all the things that should be marked @Public. As Tom Graves pointed out in an earlier discussion about @LimitedPrivate, it may be impossible to do a straightforward task and use only interfaces marked @Public. If users can't do basic things without straying from @Public interfaces then tons of code can break if we assume it's always fair game to change anything not marked @Public. The well you shouldn't have used a non-@Public interface argument is not very useful in that context. So as long as we're good about making sure officially supported features have corresponding @Public interfaces to wield them then I agree it will be easier to track those rather than track all the classes that should be @Private. Hopefully if users understand that's how things work they'll help file JIRAs for interfaces that need to be @Public to get their work done. Jason On 07/22/2014 04:54 PM, Karthik Kambatla wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
[DISCUSS] Assume Private-Unstable for classes that are not annotated
Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
That policy makes sense to me. We should still label things @Private of course so that it can be reflected in the documentation. -Sandy On Tue, Jul 22, 2014 at 2:54 PM, Karthik Kambatla ka...@cloudera.com wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
Re: [DISCUSS] Assume Private-Unstable for classes that are not annotated
+1 On Tue, Jul 22, 2014 at 3:44 PM, Sandy Ryza sandy.r...@cloudera.com wrote: That policy makes sense to me. We should still label things @Private of course so that it can be reflected in the documentation. -Sandy On Tue, Jul 22, 2014 at 2:54 PM, Karthik Kambatla ka...@cloudera.com wrote: Hi devs As you might have noticed, we have several classes and methods in them that are not annotated at all. This is seldom intentional. Avoiding incompatible changes to all these classes can be considerable baggage. I was wondering if we should add an explicit disclaimer in our compatibility guide that says, Classes without annotations are to considered @Private For methods, is it reasonable to say - Class members without specific annotations inherit the annotations of the class? Thanks Karthik
