[
https://issues.apache.org/jira/browse/HADOOP-14876?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16221518#comment-16221518
]
Robert Kanter commented on HADOOP-14876:
----------------------------------------
Thanks for writing this up [~templedf].
Some comments:
# In the compatibility doc, I think we're missing the world "element" here:
{quote}
An Unstable element MAY be removed at any time. When possible an Unstable
\[element\] SHOULD be marked...
{quote}
# In the dev guide, a minor grammer issue:
{quote}
When writing software that calls methods or uses classes that belong to Apache
Hadoop, developer\[s\] should adhere to the following guidelines.
{quote}
# I assume this also includes fields?
{quote}
Downstream developers should only use packages, classes, and methods that are
marked as Public
{quote}
# It would be good to clarify what has priority in the case of an
inconsistently marked (stability or privacy) element. For example, if a class
is marked private but a method in that class is marked public.
# For clarify:
{quote}
\[For example,\] \[t\]hat means that if a Stable is marked as deprecated in
Hadoop 3.1, it cannot be removed until Hadoop 5.0.
{quote}
# Spelling:
{quote}
In cases where the JavaDocs are insufficient to infere expected behavior...
{quote}
"infere" should be "infer"
# This seems repetative:
{quote}
The Apache Hadoop developer community strives to ensure that the behavior of
APIs remains consistent across releases, though changes for correctness may
result in changes in behavior.
{quote}
And then two paragraphs later:
{quote}
Be aware that fixes done for correctness reasons may cause changes to the
expected behavior of an API, though such changes are expected to be accompanied
by documentation that clarifies the new behavior.
{quote}
# Missing a letter:
{quote}
The default property values will not be changed during a maintainance
releas\[e\].
{quote}
# Extra letter:
{quote}
It is the goal of the Hadoop development community to allow application code to
continued to function unchanged...
{quote}
"continued" should be "continue"
# "hadoop-mapreduce-client-hs" and "hadoop-mapreduce-client-hs-plugins" are
listed as client artifacts, and their naming also suggests that; but are they
really? This is the Job History Server code, which I wouldn't think is
actually a client artifact...
Some stray thoughts:
- This was funny:
{quote}
The deprecated element should continue to function, but may and likely will be
removed in a subsequent release.
{quote}
Haha, {{DistributedCache}} has been deprecated since 2013 :)
- I find it ironic, or at least interesting, that we maintain binary
compatibility for MapReduce Applications across releases, but not for MapReduce
itself.
> Create downstream developer docs from the compatibility guidelines
> ------------------------------------------------------------------
>
> Key: HADOOP-14876
> URL: https://issues.apache.org/jira/browse/HADOOP-14876
> Project: Hadoop Common
> Issue Type: Improvement
> Components: documentation
> Affects Versions: 3.0.0-beta1
> Reporter: Daniel Templeton
> Assignee: Daniel Templeton
> Priority: Critical
> Attachments: Compatibility.pdf, DownstreamDev.pdf,
> HADOOP-14876.001.patch, HADOOP-14876.002.patch
>
>
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
