hadoop-common-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tom White (JIRA)" <j...@apache.org>
Subject [jira] Updated: (HADOOP-6668) Apply audience and stability annotations to classes in common
Date Thu, 01 Apr 2010 22:24:27 GMT

     [ 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.


Mime
View raw message