[jira] Updated: (HADOOP-6668) Apply audience and stability annotations to classes in common

["Tom White (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/HADOOP-6668?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Tom White updated HADOOP-6668:
------------------------------

    Attachment: HADOOP-6668.patch

I have had a first attempt at applying annotations to the common codebase. They are summarized in this table; consult the patch for finer-grained detail.

||Package org.apache.hadoop.|| Visibility & Stability || Notes ||
|classification|public stable| Should we mark them evolving?|
|conf|public stable| |
|fs|public stable|filesystem implementations are public stable, but any internal classes are private unstable|
|fs.shell|private unstable| |
|http|limited-private unstable| |
|io|public stable| |
|io.compress|public stable| |
|io.compress.bzip2|private unstable| |
|io.compress.zlib|private unstable| |
|io.file.tfile|public evolving| |
|io.retry|limited-private evolving| |
|io.serializer*|public evolving| |
|ipc*|limited-private evolving| |
|metrics*|public evolving| |
|net|mixture of public evolving and limited-private unstable| |
|record*|deprecated| |
|security*|mixture of public/limited-private evolving?| |
|util|public evolving|GenericOptionsParser, ReflectionUtils, Progressable, Tool, ToolRunner are public stable|
|util.bloom|public stable| |
|util.hash|public stable| |

I haven't annotated the security APIs yet - if anyone has suggestions for these, I'd be grateful.

I'm wondering whether to mark deprecated elements as 'evolving' (if they were deprecated in 0.19 or earlier), so that they can be removed sooner than the next major release. We wouldn't necessarily do this, but it might be wise to have the option.

Here are some guidelines that I used in applying the annotations. Selecting the annotations to apply is a judgement call, so I'd appreciate feedback both on the general rules and the particular annotations I have applied.
* Public user APIs should be marked as 'public stable'. These appear in public Javadoc.
* APIs that are exposed to the user but not coded against directly should be marked as 'public evolving' (e.g. the metrics API, which is used in configuration).  These appear in public Javadoc.
* Non-user facing APIs that are used within Hadoop subprojects should be marked as 'limited-private evolving' (e.g. RPC) or 'limited-private unstable'. These appear in developer Javadoc.
* Anything that is private implementation code should be marked as 'private unstable'. These appear in developer Javadoc.
* If an API is not annotated then it defaults to the usual Java visibility and Apache Hadoop stability (http://wiki.apache.org/hadoop/Roadmap) rules.


> Apply audience and stability annotations to classes in common
> -------------------------------------------------------------
>
>                 Key: HADOOP-6668
>                 URL: https://issues.apache.org/jira/browse/HADOOP-6668
>             Project: Hadoop Common
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Tom White
>            Assignee: Tom White
>         Attachments: HADOOP-6668.patch
>
>
> Mark private implementation classes with the InterfaceAudience.Private or InterfaceAudience.LimitedPrivate annotation to exclude them from user Javadoc and JDiff.

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