How should we progress here? Unless objection by tomorrow -- a week -- then lets just adopt this doc? I can squash it into our dev section in refguide. St.Ack
On Sat, Nov 15, 2014 at 5:06 PM, lars hofhansl <[email protected]> wrote: > 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.) > >
