Repository: hadoop Updated Branches: refs/heads/HDFS-9806 64be4098a -> 36957f0d2 (forced update)
HADOOP-13493. Compatibility Docs should clarify the policy for what takes precedence when a conflict is found (templedf via rkanter) Project: http://git-wip-us.apache.org/repos/asf/hadoop/repo Commit: http://git-wip-us.apache.org/repos/asf/hadoop/commit/75a3ab88 Tree: http://git-wip-us.apache.org/repos/asf/hadoop/tree/75a3ab88 Diff: http://git-wip-us.apache.org/repos/asf/hadoop/diff/75a3ab88 Branch: refs/heads/HDFS-9806 Commit: 75a3ab88f5f4ea6abf0a56cb8058e17b5a5fe403 Parents: 0e560f3 Author: Robert Kanter <rkan...@apache.org> Authored: Thu Nov 30 07:39:15 2017 -0800 Committer: Robert Kanter <rkan...@apache.org> Committed: Thu Nov 30 07:39:15 2017 -0800 ---------------------------------------------------------------------- .../src/site/markdown/Compatibility.md | 29 +++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hadoop/blob/75a3ab88/hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md ---------------------------------------------------------------------- diff --git a/hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md b/hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md index 461ff17..54be412 100644 --- a/hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md +++ b/hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md @@ -117,13 +117,7 @@ Compatibility types Developers SHOULD annotate all Hadoop interfaces and classes with the @InterfaceAudience and @InterfaceStability annotations to describe the -intended audience and stability. Annotations may be at the package, class, or -member variable or method level. Member variable and method annotations SHALL -override class annotations, and class annotations SHALL override package -annotations. A package, class, or member variable or method that is not -annotated SHALL be interpreted as implicitly -[Private](./InterfaceClassification.html#Private) and -[Unstable](./InterfaceClassification.html#Unstable). +intended audience and stability. * @InterfaceAudience captures the intended audience. Possible values are [Public](./InterfaceClassification.html#Public) (for end users and external @@ -134,6 +128,27 @@ etc.), and [Private](./InterfaceClassification.html#Private) * @InterfaceStability describes what types of interface changes are permitted. Possible values are [Stable](./InterfaceClassification.html#Stable), [Evolving](./InterfaceClassification.html#Evolving), and [Unstable](./InterfaceClassification.html#Unstable). * @Deprecated notes that the package, class, or member variable or method could potentially be removed in the future and should not be used. +Annotations MAY be applied at the package, class, or method level. If a method +has no privacy or stability annotation, it SHALL inherit its intended audience +or stability level from the class to which it belongs. If a class has no +privacy or stability annotation, it SHALL inherit its intended audience or +stability level from the package to which it belongs. If a package has no +privacy or stability annotation, it SHALL be assumed to be +[Private](./InterfaceClassification.html#Private) and +[Unstable](./InterfaceClassification.html#Unstable), +respectively. + +In the event that an element's audience or stability annotation conflicts with +the corresponding annotation of its parent (whether explicit or inherited), the +element's audience or stability (respectively) SHALL be determined by the +more restrictive annotation. For example, if a +[Private](./InterfaceClassification.html#Private) method is contained +in a [Public](./InterfaceClassification.html#Public) class, then the method +SHALL be treated as [Private](./InterfaceClassification.html#Private). If a +[Public](./InterfaceClassification.html#Public) method is contained in a +[Private](./InterfaceClassification.html#Private) class, the method SHALL be +treated as [Private](./InterfaceClassification.html#Private). + #### Use Cases * [Public](./InterfaceClassification.html#Public)-[Stable](./InterfaceClassification.html#Stable) API compatibility is required to ensure end-user programs and downstream projects continue to work without modification. --------------------------------------------------------------------- To unsubscribe, e-mail: common-commits-unsubscr...@hadoop.apache.org For additional commands, e-mail: common-commits-h...@hadoop.apache.org