Uploaded image for project: 'Accumulo'
  1. Accumulo
  2. ACCUMULO-2590

Update public API in readme to clarify what's included

    Details

    • Type: Task
    • Status: Resolved
    • Priority: Blocker
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 1.6.0
    • Component/s: docs
    • Labels:
      None

      Description

      Due to confusion expressed on the mailing list, edit the README section on the public API to make unambiguous:

      1. the list of packages included (e.g. "all packages under org.apache.accumulo.core.client, save those named 'impl'")
      2. that public Classes and Interfaces in those packages are covered
      3. that within said Classes and Interfaces, we include
        1. public and protected members
        2. public and protected methods
        3. public and protected constructors
        4. public and protected inner Classes and Interfaces

      And that "compatibility" means binary compatibility as defined in the Java Language Spec v3, Chapter 13

        Issue Links

          Activity

          Hide
          mdrob Mike Drob added a comment -

          Do we need to make explicit that public inner classes are public API all the way down? i.e. if an inner class has an inner class, the inner-inner class will still be public, and so on.

          Show
          mdrob Mike Drob added a comment - Do we need to make explicit that public inner classes are public API all the way down? i.e. if an inner class has an inner class, the inner-inner class will still be public, and so on.
          Hide
          kturner Keith Turner added a comment -

          Do we need to make explicit that public inner classes are public API all the way down? i.e. if an inner class has an inner class, the inner-inner class will still be public, and so on.

          That would be my expectation. Anything public or protected in an API class is part or the API. This would include methods, variables, classes, interfaces, and enums in the class. Did i miss anything?

          Show
          kturner Keith Turner added a comment - Do we need to make explicit that public inner classes are public API all the way down? i.e. if an inner class has an inner class, the inner-inner class will still be public, and so on. That would be my expectation. Anything public or protected in an API class is part or the API. This would include methods, variables, classes, interfaces, and enums in the class. Did i miss anything?
          Hide
          busbey Sean Busbey added a comment -

          Anything public or protected in an API class is part or the API. This would include methods, variables, classes, interfaces, and enums in the class. Did i miss anything?

          I think that's everything. I like that phrasing better as well.

          Show
          busbey Sean Busbey added a comment - Anything public or protected in an API class is part or the API. This would include methods, variables, classes, interfaces, and enums in the class. Did i miss anything? I think that's everything. I like that phrasing better as well.
          Hide
          busbey Sean Busbey added a comment -

          How's this suggested patch look for clarifying things?

          Show
          busbey Sean Busbey added a comment - How's this suggested patch look for clarifying things?
          Hide
          elserj Josh Elser added a comment -

          LGTM

          Show
          elserj Josh Elser added a comment - LGTM
          Hide
          kturner Keith Turner added a comment -

          Would it be useful to also to make a statement about compatible between 1.X and 1.(x+1) releases. Deprecated methods may be dropped and methods may be added. Anything not deprecated should continue to work.

          Show
          kturner Keith Turner added a comment - Would it be useful to also to make a statement about compatible between 1.X and 1.(x+1) releases. Deprecated methods may be dropped and methods may be added. Anything not deprecated should continue to work.
          Hide
          busbey Sean Busbey added a comment -

          How about if I quote the release governance document

          API changes should only be made on major releases, with continued support of the previous API for at least one major revision.

          I'd link to it, but our current README format doesn't lend itself well to that.

          Show
          busbey Sean Busbey added a comment - How about if I quote the release governance document API changes should only be made on major releases, with continued support of the previous API for at least one major revision. I'd link to it, but our current README format doesn't lend itself well to that.
          Hide
          kturner Keith Turner added a comment -

          sounds good

          Show
          kturner Keith Turner added a comment - sounds good
          Hide
          jira-bot ASF subversion and git services added a comment -

          Commit d896bf37d2dcf1834e32425b7364e6d5963e4c12 in accumulo's branch refs/heads/1.6.0-SNAPSHOT from Sean Busbey
          [ https://git-wip-us.apache.org/repos/asf?p=accumulo.git;h=d896bf3 ]

          ACCUMULO-2590 Updates our Public API declaration to be more explicit.

          Show
          jira-bot ASF subversion and git services added a comment - Commit d896bf37d2dcf1834e32425b7364e6d5963e4c12 in accumulo's branch refs/heads/1.6.0-SNAPSHOT from Sean Busbey [ https://git-wip-us.apache.org/repos/asf?p=accumulo.git;h=d896bf3 ] ACCUMULO-2590 Updates our Public API declaration to be more explicit.
          Hide
          jira-bot ASF subversion and git services added a comment -

          Commit d896bf37d2dcf1834e32425b7364e6d5963e4c12 in accumulo's branch refs/heads/master from Sean Busbey
          [ https://git-wip-us.apache.org/repos/asf?p=accumulo.git;h=d896bf3 ]

          ACCUMULO-2590 Updates our Public API declaration to be more explicit.

          Show
          jira-bot ASF subversion and git services added a comment - Commit d896bf37d2dcf1834e32425b7364e6d5963e4c12 in accumulo's branch refs/heads/master from Sean Busbey [ https://git-wip-us.apache.org/repos/asf?p=accumulo.git;h=d896bf3 ] ACCUMULO-2590 Updates our Public API declaration to be more explicit.

            People

            • Assignee:
              busbey Sean Busbey
              Reporter:
              busbey Sean Busbey
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development