hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lars hofhansl <la...@apache.org>
Subject HBase - Semantic Versioning
Date Sun, 16 Nov 2014 01:06:26 GMT
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.)


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message