[jira] [Commented] (NIFI-1373) Annotate all classes to indicate their API stability and intended audience
[ https://issues.apache.org/jira/browse/NIFI-1373?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15318965#comment-15318965 ] Mark Payne commented on NIFI-1373: -- I have created a JIRA in the Yetus JIRA tracker and linked to it from here. Thanks, [~busbey]! > Annotate all classes to indicate their API stability and intended audience > -- > > Key: NIFI-1373 > URL: https://issues.apache.org/jira/browse/NIFI-1373 > Project: Apache NiFi > Issue Type: Task > Components: Core Framework, Core UI, Extensions >Reporter: Joseph Witt >Assignee: Joseph Witt > Fix For: 1.0.0 > > > Sean Busbey and Tony Kurc have pointed out the need to document the intended > audience and stability of the APIs. This is very necessary as we need to be > able to make changes and be fluid where intended and extremely strict to > compatibility where intended. Presently with things being unmarked it can be > ambiguous for those not deeply familiar with the api and codebase. > By leveraging the annotations from Apache Yetus we can resolve this > discrepancy across the codebase: > http://yetus.apache.org/documentation/0.1.0/audience-annotations-apidocs/ -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (NIFI-1373) Annotate all classes to indicate their API stability and intended audience
[ https://issues.apache.org/jira/browse/NIFI-1373?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15318665#comment-15318665 ] Sean Busbey commented on NIFI-1373: --- I don't think there's something inherent in the current annotations that provide that kind of distinction, but the project could build it. For example, you could do that with an audience annotation. normally I don't care for the "LimitedPrivate" audience level, but you could use it on such interfaces with a detail that indicates it's for downstream consumption but not implementation. One way to avoid using LimitedPrivate for this would be to open a feature request against Yetus to have the Public interface audience add a similar "detail" field. I think the use of java interfaces in apis where downstream users aren't expected to implement the interfaces themselves should be pretty common, so maybe this is worth a specific solution (either on the InterfaceStability as you mention or on the InterfaceAudience). Mind opening a jira in the YETUS tracker, or just emailing the dev@yetus list? > Annotate all classes to indicate their API stability and intended audience > -- > > Key: NIFI-1373 > URL: https://issues.apache.org/jira/browse/NIFI-1373 > Project: Apache NiFi > Issue Type: Task > Components: Core Framework, Core UI, Extensions >Reporter: Joseph Witt >Assignee: Joseph Witt > Fix For: 1.0.0 > > > Sean Busbey and Tony Kurc have pointed out the need to document the intended > audience and stability of the APIs. This is very necessary as we need to be > able to make changes and be fluid where intended and extremely strict to > compatibility where intended. Presently with things being unmarked it can be > ambiguous for those not deeply familiar with the api and codebase. > By leveraging the annotations from Apache Yetus we can resolve this > discrepancy across the codebase: > http://yetus.apache.org/documentation/0.1.0/audience-annotations-apidocs/ -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (NIFI-1373) Annotate all classes to indicate their API stability and intended audience
[ https://issues.apache.org/jira/browse/NIFI-1373?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15314523#comment-15314523 ] Mark Payne commented on NIFI-1373: -- [~joewitt] [~tkurc] [~busbey] Do these annotations provide any sort of notion of "Implementation Stability" vs. "Dependency Stability"? For example, our ProcessContext class is very stable in terms of any existing method will not have its signature or functionality change, so you can feel at ease knowing that the code you've written that makes use of ProcessContext will continue to work between minor versions. However, we may well add new methods to this interface between minor versions, so others should not be trying to implement this interface. Are these two notions taken into consideration when using the InterfaceStability annotation? > Annotate all classes to indicate their API stability and intended audience > -- > > Key: NIFI-1373 > URL: https://issues.apache.org/jira/browse/NIFI-1373 > Project: Apache NiFi > Issue Type: Task > Components: Core Framework, Core UI, Extensions >Reporter: Joseph Witt >Assignee: Joseph Witt > Fix For: 1.0.0 > > > Sean Busbey and Tony Kurc have pointed out the need to document the intended > audience and stability of the APIs. This is very necessary as we need to be > able to make changes and be fluid where intended and extremely strict to > compatibility where intended. Presently with things being unmarked it can be > ambiguous for those not deeply familiar with the api and codebase. > By leveraging the annotations from Apache Yetus we can resolve this > discrepancy across the codebase: > http://yetus.apache.org/documentation/0.1.0/audience-annotations-apidocs/ -- This message was sent by Atlassian JIRA (v6.3.4#6332)