You are viewing a plain text version of this content. The canonical link for it is here.
Posted to common-issues@hadoop.apache.org by "Sanjay Radia (JIRA)" <ji...@apache.org> on 2010/05/19 22:41:53 UTC
[jira] Created: (HADOOP-6775) Update Hadoop Common Site's
Update Hadoop Common Site's
----------------------------
Key: HADOOP-6775
URL: https://issues.apache.org/jira/browse/HADOOP-6775
Project: Hadoop Common
Issue Type: Improvement
Reporter: Sanjay Radia
Assignee: Sanjay Radia
Fix For: site
Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12869814#action_12869814 ]
Sanjay Radia commented on HADOOP-6775:
--------------------------------------
I was planning to add the following item to the FAQ section. Would this address your comment?
<add to FAQ section>
How does the classification relate to the Java's visibility declaration?
Java allows public, private and protected declarations.
• A java-private element is always audience-private.
• An audience-public element is always java-public; the reverse is not always true. One is often forced to make an API java-public to allow related packages to access the API. Such java-public APIs may be classified as audience-limited-private or even audience-private.
• A java-protected element may be audience-private (for internal sub-classing within an implementation), or audience-public if it is intended for general use (as with HDFS's AbstractFileSystem class).
• If JSR-294 completes (currently inactive) it will likely help in aligning our classification with the Java visibility rules: it appears that one of the goals of the JSR-294 is to better deal with visibility across peer-packages; this would allow us to capture most of the use cases for limited-private.
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12871857#action_12871857 ]
Doug Cutting commented on HADOOP-6775:
--------------------------------------
Does this really belong on the project website, or rather in the product's documentation? I can see the argument that it's about project policy, independent of any release, but also think this documentation should be included with releases, since it's relevant to end users, not just developers. Also, it might evolve, and perhaps should be versioned with releases. So, on balance, I think perhaps adding it to the product rather than the project is more appropriate. Thoughts?
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Sanjay Radia updated HADOOP-6775:
---------------------------------
Attachment: siteCLassification3.patch
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Jakob Homan (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Jakob Homan updated HADOOP-6775:
--------------------------------
Summary: Update Hadoop Common Sites (was: Update Hadoop Common Site's )
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Sanjay Radia updated HADOOP-6775:
---------------------------------
Attachment: siteCLassification2.patch
Fixed typo (hdfs -> HDFS).
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: siteCLassification.patch, siteCLassification2.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Chris Douglas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12871960#action_12871960 ]
Chris Douglas commented on HADOOP-6775:
---------------------------------------
bq. Also, it might evolve, and perhaps should be versioned with releases. So, on balance, I think perhaps adding it to the product rather than the project is more appropriate. Thoughts?
So that future bylaws, release policies, etc. can reference it, packaging it with the site documentation could make things slightly easier... Modifying the definitions to apply to releases of the product- requiring us to have a tedious discussion about whether these rules are recursive and malleable within a major/patch release- doesn't seem like a useful capability. It's relevant to end users, but this FAQ- if posted to site- can change independently of Hadoop releases, which is also useful.
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12869375#action_12869375 ]
Doug Cutting commented on HADOOP-6775:
--------------------------------------
It would be nice if our interface classification scheme is as compatible as possible with Java's built-in visibility declarations. These unfortunately do not permit sharing of non-public classes between packages, which makes it difficult to build a large system, however JSR-294 appears to fix this in Java 7.
Can you please describe in this document the relationship between Java's built-in visibility declarations and this scheme, both before and after JSR-294? Ideally the correspondence would be fairly direct, so that tools like Javadoc, javac, eclipse, etc. that enforce Java's visibility declarations work as effectively as possible with Hadoop code.
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: siteCLassification.patch, siteCLassification2.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12870049#action_12870049 ]
Doug Cutting commented on HADOOP-6775:
--------------------------------------
+1 to this FAQ. Thanks for adding it so quickly!
My only nit is that I'm not convinced that the "inactive" status of JSR-294 is significant and bears noting. It looks like a JSR automatically enters this status if its proposal has not been updated in 18 months. However work on this feature appears to be active in Project Jigsaw, and JSR-294 is still listed in the public roadmap for Java 7.
http://openjdk.java.net/projects/jdk7/features/
So we might just say that we expect JSR-294 to help in Java 7. Fair?
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Sanjay Radia updated HADOOP-6775:
---------------------------------
Attachment: siteCLassification.patch
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: siteCLassification.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12871980#action_12871980 ]
Doug Cutting commented on HADOOP-6775:
--------------------------------------
> So that future bylaws, release policies, etc. can reference it, packaging it with the site documentation could make things slightly easier...
We're able to refer to product documentation from the site with a relative link to docs/current, and we're able to refer to site documentation from the product documentation with links to http://hadoop.apache.org/.
A case I'm worried about is that if we, e.g., rename or remove one of these categories, then released documentation would no longer make sense. The definition of these terms seems like a part of the product documentation, not a part of the project policy. How we apply and enforce the terms is a matter of policy.
Most project policy has typically been documented on the wiki, not the website. Should we change that?
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Sanjay Radia updated HADOOP-6775:
---------------------------------
Attachment: api_classification.pdf
For convenience I have attached the pdf generated by forrest.
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Eli Collins (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12871846#action_12871846 ]
Eli Collins commented on HADOOP-6775:
-------------------------------------
Looks good to me Sanjay.
Can we clarify the 2nd bullet a little more, my understanding is that the default classification (unless otherwise specified) of public classes and public methods is audience-private, which is why we've been able to remove public classes and rename public methods. Is that correct?
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Site's
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12870096#action_12870096 ]
Sanjay Radia commented on HADOOP-6775:
--------------------------------------
> So we might just say that we expect JSR-294 to help in Java 7. Fair?
Absolutely.
I will change my comment about "inactive" to something along the lines that the there is ongoing work that is likely to help our classification work.
> Update Hadoop Common Site's
> ----------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Doug Cutting (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12872285#action_12872285 ]
Doug Cutting commented on HADOOP-6775:
--------------------------------------
So, if we decide to add this to the site, should we also add something to the product that points to this document?
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Chris Douglas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12872034#action_12872034 ]
Chris Douglas commented on HADOOP-6775:
---------------------------------------
bq. A case I'm worried about is that if we, e.g., rename or remove one of these categories, then released documentation would no longer make sense. The definition of these terms seems like a part of the product documentation, not a part of the project policy. How we apply and enforce the terms is a matter of policy.
As I said, I don't see this as a useful capability. If the project elects to change one of the labels or its meaning, the page will be required to list that history to be coherent, e.g. "Versions x.y-x.z used LimitedPrivate instead of StayAwayLusers, but the two may be regarded as equivalent".
I didn't mean to imply that the mechanics of linking were a sound motivation; I'm pretty sure that's a solved problem for webpages. I meant that changing these rules need not be tied to a particular release, but could apply to development in progress. Like 0.21.
bq. Most project policy has typically been documented on the wiki, not the website. Should we change that?
Sometimes. Do we really need to debate a policy on this?
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (HADOOP-6775) Update Hadoop Common Sites
Posted by "Sanjay Radia (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HADOOP-6775?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12873107#action_12873107 ]
Sanjay Radia commented on HADOOP-6775:
--------------------------------------
> Can we clarify the 2nd bullet a little more, my understanding is that the default classification (unless otherwise specified)...
Okay.
> Project vs product...
The classification/taxonomy is part of the project definition and cuts across releases (indeed the stable tag by its very definition states what remains the same across releases).
>Project site vs wiki ...
The reason I used the project site rather than the wiki was because of the importance of the classification and it very direct impact on compatibility and on the definition of the Hadoop platform (ie the public APIs define the hadoop platform).
> Update Hadoop Common Sites
> ---------------------------
>
> Key: HADOOP-6775
> URL: https://issues.apache.org/jira/browse/HADOOP-6775
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Sanjay Radia
> Assignee: Sanjay Radia
> Fix For: site
>
> Attachments: api_classification.pdf, siteCLassification.patch, siteCLassification2.patch, siteCLassification3.patch
>
>
> Add documentation on our interface classification scheme to thew common site.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.