[jira] [Updated] (HADOOP-14876) Create downstream developer docs from the compatibility guidelines

["Daniel Templeton (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/HADOOP-14876?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Daniel Templeton updated HADOOP-14876:
--------------------------------------
    Attachment: HADOOP-14876.005.patch

Thanks for the thoughtful review, [~anu].

bq. Use cases Matrix

OK

bq. It would be good to define which kind of releases are possible

Fair point

bq. Semantic compatibility

Good point.  I don't think this goes in the API section or the config section.  I've added a new section to address functional compatibility.

bq. may I suggest that we add the word "current"

Done

bq. "that are meaningful to Hadoop" – This is a very loose definition

The intent is indeed that no env vars that are interpreted by Hadoop will change in their interpretation between minor releases.  I'll see if I can come up with a clearer way to say that.

bq. As a non-native English language speaker, I wonder if this statement is ambiguous

I don't think it is. It's phrased that way because the compat spec is intended as a spec. "held stable" is definitely easier to read, but it's not specific enough.

Looks like I left native dependencies out of the dev guide.  I've added it in now.

bq. I don't think that we can treat S3 or Kerberos as internal protocols.

bq. Did you mean to write, default service ports instead of fixed?

Good catch.

bq. New transport mechanisms MUST only be introduced with minor or major version changes.

I'm OK with removing this constraint. I no longer remember why it's there. :)

bq. Should we just remove the automation phrase?

I think the problem is less the automation phrase and more the policy below it. I agree that restricting log output changes to minor releases is too draconian. We'll end up excluding patches from being backported for dubious reasons. I've relaxed the policy to Unstable.

bq. If we have an upgrade path, I submit that this should be possible.

I updated the data node section to talk about upgrade paths instead.

bq. Are we sure that 3.0 release is entirely complaint to this spec?

I wouldn't be surprised if it weren't. The slaves.txt file isn't explicitly covered by this spec.  The CLI policy is only concerned with command output.  I think slaves.txt should fall under the configuration policy, though it's not currently covered there.  Given that there are several non-XML config files now, it seems that's an oversight I should correct. When you're asking if the change is compatible, do you mean the renaming of the file?

bq. Do you have a case where this has happened? If not, we should allow this change. "user-accessible" is an extensive term.

The policy is below in the policy section.  There we specifically enumerate the things that can't change in a maintenance release and declare everything else free to change. I also added a section at the top to better explain the structure of the document.

bq. We should have a full list of supported version documented somewhere.

I agree.  There is no such document that I know of.

> 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, HADOOP-14876.003.patch, HADOOP-14876.004.patch, HADOOP-14876.005.patch
>
>




--
This message was sent by Atlassian JIRA
(v6.4.14#64029)

---------------------------------------------------------------------
To unsubscribe, e-mail: common-issues-unsubscribe@hadoop.apache.org
For additional commands, e-mail: common-issues-help@hadoop.apache.org