HBASE-17823 Update to Yetus Audience Annotations #58
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mdlinville
suggested changes
Aug 30, 2017
| @@ -125,10 +125,10 @@ for warning about incompatible changes). All effort will be made to provide a de | |||
| [[hbase.client.api.surface]] | |||
| ==== HBase API Surface | |||
|
|
|||
| HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses a version of link:https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/Compatibility.html[Hadoop's Interface classification]. HBase's Interface classification classes can be found link:https://hbase.apache.org/apidocs/org/apache/hadoop/hbase/classification/package-summary.html[here]. | |||
| HBase has a lot of API points, but for the compatibility matrix above, we differentiate between Client API, Limited Private API, and Private API. HBase uses link:http://yetus.apache.org/documentation/0.5.0/interface-classification/[Apache Yetus Audience Annotations] to guide downstream expectations for stability. In previous releases HBase relied on its own implementation of these classes; folks can rely on the same assumptions based on the annotation class name, but the package will be different. | |||
There was a problem hiding this comment.
I suggest breaking out Client API, Limited Private API, and Private API into a little table or list with definitions of each.
The last sentence is kind of inside baseball. I suggest something like "HBase no longer maintains its own implementation of these classes but relies on packages provided by Apache Yetus.
There was a problem hiding this comment.
a table independent of the explanation in the InterfaceAudience section below? or in place of?
There was a problem hiding this comment.
just to confirm. there is a set of sub-sections under here that has brief definitions of each of Client API, LP API, and private API:
http://hbase.apache.org/book.html#hbase.client.api.surface
I'm turning those into a table?
There was a problem hiding this comment.
It's not that important. I think I just sensed that the info was both confusing and kind of matrix-y.
|
|
||
| * InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields. | ||
| * InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details. | ||
| * InterfaceAudience (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceAudience.html[javadocs]): captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields. |
There was a problem hiding this comment.
intended audience. Possible values include:
- Public: safe for use by end users and external projects
- LimitedPrivate: safe for use for projects which need access to HBase internals, such as coprocessors or other plugin points
- Private: only for internal use within HBase itself
Classes which are defined as IA.Private may be used as parameters or return values for interfaces which are declared IA.LimitedPrivate. Treat the IA.Private object as a monolithic object when using it as a parameter to call other methods or when returning it, but do not try to access its methods or fields directly.
| * InterfaceAudience: captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields. | ||
| * InterfaceStability: describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details. | ||
| * InterfaceAudience (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceAudience.html[javadocs]): captures the intended audience, possible values are Public (for end users and external projects), LimitedPrivate (for other Projects, Coprocessors or other plugin points), and Private (for internal use). Notice that, you may find that the classes which are declared as IA.Private are used as parameter or return value for the interfaces which are declared as IA.LimitedPrivate. This is possible. You should treat the IA.Private object as a monolithic object, which means you can use it as a parameter to call other methods, or return it, but you should never try to access its methods or fields. | ||
| * InterfaceStability (link:http://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceStability.html[javadocs]): describes what types of interface changes are permitted. Possible values are Stable, Evolving, Unstable, and Deprecated. Notice that this annotation is only valid for classes which are marked as IA.LimitedPrivate. The stability of IA.Public classes is only related to the upgrade type(major, minor or patch). And for IA.Private classes, there is no guarantee on the stability between releases. Refer to the Compatibility Matrix above for more details. |
There was a problem hiding this comment.
permitted. Possible values include:
- Stable: the interface is fixed and is not expected to change.
- Evolving: the interface is relatively fixed, but may change <when?>
- Unstable: the interface may change at any time
- Deprecated: plan to update your code to use a non-deprecated class instead.
The following interactions occur between InterfaceAudience and `InterfaceStability:
iA.Publicclasses are inherently stable, and adhere to the stability guarantees relating to the type of upgrade (major, minor, or patch).InterfaceStabilitymay be any of the allowed values whenInterfaceStabilityisIA.LimitedPrivate.IA.Privateclasses should be considered inherently unstable, with no guarantee of stability between releases.
(I'm not sure where Deprecated fits here, because you can definitely have Pubic things that are deprecated -- that's the whole point, right?)
There was a problem hiding this comment.
looking at both yetus and our own internal IS settings, there is no Deprecated. so I'll just remove references to it.
|
rebasing this is super painful, so I'd like to avoid doing it another time after the one I'm doing now. Presuming I can get all of these feedback changes in place, are you +1 @mstanleyjones? |
|
I think I have your feedback in place, let me know how things look. |
mdlinville
approved these changes
Sep 11, 2017
This was referenced Jul 21, 2019
Merged
This was referenced Jul 29, 2019
This was referenced Sep 6, 2019
This was referenced Sep 14, 2019
Closed
This was referenced Sep 24, 2019
This was referenced Oct 3, 2019
This was referenced Oct 12, 2019
This was referenced Oct 22, 2019
ndimiduk
pushed a commit
to ndimiduk/hbase
that referenced
this pull request
Feb 29, 2024
Co-authored-by: Scott Williams <[email protected]>
ndimiduk
pushed a commit
to ndimiduk/hbase
that referenced
this pull request
Feb 29, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
@mstanleyjones