[jira] Commented: (HADOOP-5073) Hadoop 1.0 Interface Classification - scope (visibility - public/private) and stability

["Doug Cutting (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/HADOOP-5073?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12664692#action_12664692 ] 

Doug Cutting commented on HADOOP-5073:
--------------------------------------

This sounds fine.

The implication on documentation should be something like:
 - Public/stable should be documented.
 - Public/evolving should documented, but must be well-marked as evolving.
 - Private, limited or otherwise, should not be included in public documentation, but only in internal documents.

The marking for evolving could be as simple as adding "Evolving:" to the beginning of javadoc strings.  Or perhaps we can add an annotation and doclet which adds "Evolving" in *bold*, as is done for deprecations.  If evolving and/or deprecated features have Forrest documentation, then that too should include a marking.

We'd also need to add end-user documentation of this policy, including exactly what "Evolving" and "Deprecated" mean.  This should not include any discussion of the private classifications, only our compatibility promises for public stuff, and that anything undocumented has no compatibility promises.

Does this make sense?


> Hadoop 1.0 Interface Classification - scope (visibility - public/private) and stability
> ---------------------------------------------------------------------------------------
>
>                 Key: HADOOP-5073
>                 URL: https://issues.apache.org/jira/browse/HADOOP-5073
>             Project: Hadoop Core
>          Issue Type: Sub-task
>            Reporter: Sanjay Radia
>            Assignee: Sanjay Radia
>
> This jira proposes an interface classification for hadoop interfaces.
> The discussion was started in email alias core-dev@hadoop.apache.org in Nov 2008.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.