Looks like the formatting didn't come through. Please refer to the linked
document.
Thanks.
-- Lars
From: lars hofhansl <[email protected]>
To: Dev <[email protected]>
Sent: Saturday, November 15, 2014 5:06 PM
Subject: HBase - Semantic Versioning
As we approach the released of HBase 1.0.0, your PMC has been working hard on
documenting the exact compatibility guarantees we plan to support for HBase
versions going forward.
You can find the current version of the document here:
https://docs.google.com/document/d/1p5pP7v2OuzSSaomK2S2v7sfKky1Hex6OqwsJO0sZTUY/edit?usp=sharing
For convenience I am also including the entire text at the end of this email
(hopefully the formatting comes through).
Please have a look and let us know what you think.While we cannot possibly
include provisions for every corner case, this should be as comprehensive as
possible.Note that the semantic versioning document is itself semantically
versioned :)
Thanks.
-- Lars
--------------------------------------
HBase Semantic Versioning - 1.0.4As HBase approaches its 1.0.0 version we
should start using semantic versioning.In addition to the usual API versioning
considerations HBase has other compatibility dimensions that we need to
consider.
Compatibility Dimensions
- Client-Server wire protocol compatibility
- Allows updating client and server out of sync.
- We could only allow upgrading the server first. I.e. the server would be
backward compatible to an old client, that way new APIs are OK.
- Example: A user should be able to use an old client to connect to an
upgraded cluster.
- Server-Server protocol compatibility
- Servers of different versions can co-exist in the same cluster.
- The wire protocol between servers is compatible.
- Workers for distributed tasks, such as replication and log splitting, can
co-exist in the same cluster.
- Dependent protocols (such as using ZK for coordination) will also not be
changed.
- Example: A user can perform a rolling upgrade.
- File format compatibility
- Support file formats backward and forward compatible
- Example: File, ZK encoding, directory layout is upgraded automatically as
part of an HBase upgrade. User can rollback to the older version and everything
will continue to work.
- Client API compatibility
- Allow changing or removing existing client APIs.
- An API needs to deprecated for a major version before we will change/remove
it.
- Example: A user using a newly deprecated api does not need to modify
application code with hbase api calls until the next major version.
- Client Binary compatibility
- Old client code can run unchanged (no recompilation needed) against new
jars.
- Example: Old compiled client code will work unchanged with the new jars.
- Server-Side Limited API compatibility (taken from Hadoop)
- Internal APIs are marked as Stable, Evolving, or Unstable
- This implies binary compatibility for coprocessors and plugins (pluggable
classes, including replication) as long as these are only using marked
interfaces/classes.
- Example: Old compiled Coprocessor, Filter, or Plugin code will work
unchanged with the new jars.
- Dependency Compatibility
- An upgrade of HBase will not require an incompatible upgrade of a dependent
project, including the Java runtime.
- Example: An upgrade of Hadoop will not invalidate any of the
compatibilities guarantees we made.
- Operational Compatibility
- Metric changes
- Behavioral changes of services
- Web page APIs
Summary
- A patch upgrade is a drop-in replacement. Any change that is not Java
binary compatible would not be allowed.
- A minor upgrade requires no application/client code modification. Ideally
it would be a drop-in replacement but client code, coprocessors, filters, etc
might have to be recompiled if new jars are used.
- A major upgrade allows the HBase community to make breaking changes.
Compatibility Matrix
|
| Major | Minor | Patch |
| Client-Server wire Compatibility | N | Y | Y |
| Server-Server Compatibility | N | Y | Y |
| File Format Compatibility | N | Y | Y |
| Client API Compatibility | N | Y | Y |
| Client Binary Compatibility | N | N | Y |
| Server-Side Limited API Compatibility |
|
|
|
|
- Stable
| N | Y | Y |
|
- Evolving
| N | N | Y |
|
- Unstable
| N | N | N |
| Dependency Compatibility | N | Y | Y |
| Operational Compatibility | N | N | Y |
(Y means we support the compatibility. N means we can break it.)
