[HADOOP-13493] Compatibility Docs should clarify the policy for what takes precedence when a conflict is found

• Type: Task
• Status: Resolved
• Priority: Critical
• Resolution: Fixed
• Affects Version/s: 2.7.2
• Fix Version/s: 3.0.0
• Component/s: documentation
• Target Version/s: 3.0.0, 3.1.0
• Hadoop Flags: Reviewed
• Assignee: Daniel Templeton
• Reporter: Robert Kanter
• Created: 11/Aug/16 21:50
• Updated: 30/Nov/17 17:33
• Resolved: 30/Nov/17 15:40

Description

The Compatibility Docs (https://hadoop.apache.org/docs/r2.7.1/hadoop-project-dist/hadoop-common/Compatibility.html#Java_API) list the policies for Private, Public, not annotated, etc Classes and members, but it doesn't say what happens when there's a conflict. We should try obviously try to avoid this situation, but it would be good to explicitly state what takes precedence.

As an example, until YARN-3225 made it consistent, RefreshNodesRequest looked like this:

@Private
@Stable
public abstract class RefreshNodesRequest {
  @Public
  @Stable
  public static RefreshNodesRequest newInstance() {
    RefreshNodesRequest request = Records.newRecord(RefreshNodesRequest.class);
    return request;
  }
}

Note that the class is marked @Private, but the method is marked @Public.

In this example, I'd say that the class level should have priority.