Mailing-List: contact dev-help@hbase.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@hbase.apache.org
Received-SPF: pass (nike.apache.org: domain of lhofhansl@yahoo.com designates
 98.139.212.166 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=s2048; d=yahoo.com;
	b=mxODxCtB3mvDZ1KFGcc/uouXxH8lPsp5KgYUDQzbcEJDO+HMopuHtGUMIS7KJHLa/5Y0TxSmUvzSZZi2lNpxQudtnS+47df43DYqz8o8EWjRNEobW4Yc7dXrwpk5xa7zzN/z26H4x7L79bpi0Wzj8Sc58YIEBAInIcDp54gbCvk9L8bMHsCA8T/mLBXDmRZUbk4ypTMNJOeGtOeyc2VsQbcmK7TE6bznvMfPPfVIot6TrmYnNi3FJlkiRG9lZl3egthUiWD7JaotJU4PEdrxy5ReADq3h6+hSicUiqPF86z9uO+7WQFQVU6fs0qdixSGEem1aa9RVb7C+cZjHmHb1Q==;
Date: Sat, 22 Nov 2014 07:15:09 +0000 (UTC)
From: lars hofhansl <larsh@apache.org>
Reply-To: lars hofhansl <larsh@apache.org>
To: Sean Busbey <busbey@cloudera.com>, dev <dev@hbase.apache.org>
Message-ID: 
 <2051381587.3939557.1416640509694.JavaMail.yahoo@jws106135.mail.bf1.yahoo.com>
In-Reply-To: 
 <CAGHyZ6Kdnbquj=1dzj1ZcR=Y3ufH3LxuEw96kKSr36U0+K8Jzw@mail.gmail.com>
References: 
 <CAGHyZ6Kdnbquj=1dzj1ZcR=Y3ufH3LxuEw96kKSr36U0+K8Jzw@mail.gmail.com>
Subject: Re: HBase - Semantic Versioning
MIME-Version: 1.0
Content-Type: multipart/alternative;
	boundary="----=_Part_3939556_938862373.1416640509683"

------=_Part_3939556_938862373.1416640509683
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hey Sean,
thanks for taking a look. All good points.Send me your gmail id offlist, I'=
ll add you as editor (maybe in suggest mode). Might be easier that way.
If possible I would like to keep it to two pages total (otherwise nobody wi=
ll ever read it :) )(I tried one page, but that was not possible)

-- Lars
      From: Sean Busbey <busbey@cloudera.com>
 To: dev <dev@hbase.apache.org>=20
Cc: lars hofhansl <larsh@apache.org>=20
 Sent: Friday, November 21, 2014 5:19 PM
 Subject: Re: HBase - Semantic Versioning
  =20
First, this is excellent work and will help greatly with planning around HB=
ase deployments. I think the document is big enough, of wide enough interes=
t, and important enough that we should keep it as a page in the site outsid=
e of the ref guide. Maybe it could live near wherever we currently keep our=
 bylaws?
A very brief restatement of how major, minor, and patch map to version stri=
ngs X.Y.Z would help make the compatibility matrix easier to follow for tho=
se not familiar with semantic versioning. Some may go read the full referen=
ce, but most probably won't. Maybe "Summary" could be retitled "Version Cha=
nges" and the bullet points could be preceded with a couple of sentences.
I notice the document doesn't make any reference to our use of InterfaceAud=
ience[1]. Can we update it to do so?
Specifically, what is covered in "Client API", is it just stuff that's IA.P=
ublic in hbase-client or IA.Public anywhere? If the former, then what cover=
s the rest?
I think the section on "server side limited API compatibility" is for thing=
s marked IA.LimitedPrivate, but it would be nice to have it spelled out.=C2=
=A0
The document covers InterfaceStability markings but only for server side. O=
ur current ref guide[1] covers them only for things marked public. Can we u=
nify this one way or the other? I suspect the answer is that we ought to ha=
ve them for both.
[1]:=C2=A0http://hbase.apache.org/book.html#d0e21466


On Fri, Nov 21, 2014 at 6:15 PM, Stack <stack@duboce.net> wrote:

How should we progress here?=C2=A0 Unless objection by tomorrow -- a week -=
-
then lets just adopt this doc?=C2=A0 I can squash it into our dev section i=
n
refguide.
St.Ack

On Sat, Nov 15, 2014 at 5:06 PM, lars hofhansl <larsh@apache.org> wrote:

> As we approach the released of HBase 1.0.0, your PMC has been working har=
d
> 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/1p5pP7v2OuzSSaomK2S2v7sfKky1Hex6OqwsJO=
0sZTUY/edit?usp=3Dsharing
>
> 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 possibl=
y
> 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 w=
e
> need to consider.
> Compatibility Dimensions
>
>=C2=A0 =C2=A0 - Client-Server wire protocol compatibility
>
>=C2=A0 =C2=A0 - Allows updating client and server out of sync.
>=C2=A0 =C2=A0 - We could only allow upgrading the server first. I.e. the s=
erver would
> be backward compatible to an old client, that way new APIs are OK.
>=C2=A0 =C2=A0 - Example: A user should be able to use an old client to con=
nect to an
> upgraded cluster.
>
>=C2=A0 =C2=A0 - Server-Server protocol compatibility
>
>=C2=A0 =C2=A0 - Servers of different versions can co-exist in the same clu=
ster.
>=C2=A0 =C2=A0 - The wire protocol between servers is compatible.
>=C2=A0 =C2=A0 - Workers for distributed tasks, such as replication and log=
 splitting,
> can co-exist in the same cluster.
>=C2=A0 =C2=A0 - Dependent protocols (such as using ZK for coordination) wi=
ll also not
> be changed.
>=C2=A0 =C2=A0 - Example: A user can perform a rolling upgrade.
>
>=C2=A0 =C2=A0 - File format compatibility
>
>=C2=A0 =C2=A0 - Support file formats backward and forward compatible
>=C2=A0 =C2=A0 - 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.
>
>=C2=A0 =C2=A0 - Client API compatibility
>
>=C2=A0 =C2=A0 - Allow changing or removing existing client APIs.
>=C2=A0 =C2=A0 - An API needs to deprecated for a major version before we w=
ill
> change/remove it.
>=C2=A0 =C2=A0 - Example: A user using a newly deprecated api does not need=
 to modify
> application code with hbase api calls until the next major version.
>
>=C2=A0 =C2=A0 - Client Binary compatibility
>
>=C2=A0 =C2=A0 - Old client code can run unchanged (no recompilation needed=
) against
> new jars.
>=C2=A0 =C2=A0 - Example: Old compiled client code will work unchanged with=
 the new
> jars.
>
>=C2=A0 =C2=A0 - Server-Side Limited API compatibility (taken from Hadoop)
>
>=C2=A0 =C2=A0 - Internal APIs are marked as Stable, Evolving, or Unstable
>=C2=A0 =C2=A0 - This implies binary compatibility for coprocessors and plu=
gins
> (pluggable classes, including replication) as long as these are only usin=
g
> marked interfaces/classes.
>=C2=A0 =C2=A0 - Example: Old compiled Coprocessor, Filter, or Plugin code =
will work
> unchanged with the new jars.
>
>=C2=A0 =C2=A0 - Dependency Compatibility
>
>=C2=A0 =C2=A0 - An upgrade of HBase will not require an incompatible upgra=
de of a
> dependent project, including the Java runtime.
>=C2=A0 =C2=A0 - Example: An upgrade of Hadoop will not invalidate any of t=
he
> compatibilities guarantees we made.
>
>=C2=A0 =C2=A0 - Operational Compatibility
>
>=C2=A0 =C2=A0 - Metric changes
>=C2=A0 =C2=A0 - Behavioral changes of services
>=C2=A0 =C2=A0 - Web page APIs
>
> Summary
>
>=C2=A0 =C2=A0 - A patch upgrade is a drop-in replacement. Any change that =
is not Java
> binary compatible would not be allowed.
>=C2=A0 =C2=A0 - A minor upgrade requires no application/client code modifi=
cation.
> Ideally it would be a drop-in replacement but client code, coprocessors,
> filters, etc might have to be recompiled if new jars are used.
>=C2=A0 =C2=A0 - A major upgrade allows the HBase community to make breakin=
g changes.
>
>
> Compatibility Matrix
>
> |
>=C2=A0 | 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 |
>=C2=A0 |
>=C2=A0 |
>=C2=A0 |
> |
>=C2=A0 =C2=A0 - Stable
>=C2=A0 | N | Y | Y |
> |
>=C2=A0 =C2=A0 - Evolving
>=C2=A0 | N | N | Y |
> |
>=C2=A0 =C2=A0 - Unstable
>=C2=A0 | 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.)
>
>


--=20
Sean

  
------=_Part_3939556_938862373.1416640509683--