Mailing-List: contact dev-help@hbase.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@hbase.apache.org
Received-SPF: softfail (athena.apache.org: transitioning domain of
 josh.elser@gmail.com does not designate 54.191.145.13 as permitted sender)
Message-ID: <5537DBF5.6080204@gmail.com>
Date: Wed, 22 Apr 2015 13:35:49 -0400
From: Josh Elser <josh.elser@gmail.com>
User-Agent: Postbox 3.0.11 (Macintosh/20140602)
MIME-Version: 1.0
To: dev@hbase.apache.org
Subject: Re: Clarifying interface evolution freedom in patch releases (was:
 Re: [VOTE] Third release candidate for HBase 1.0.1 (RC2))
References: 
 <CA+RK=_CkTUfa3nWPsy2A0PZt07h=1stP72rcazBrw5U0JFdgXA@mail.gmail.com>
 <5537D45D.3020207@gmail.com>
 <CAGHyZ6L3kMQgACjujFyGBOiKbHNXW=-hc=7+G-cE-+y5BDSakg@mail.gmail.com>
In-Reply-To: 
 <CAGHyZ6L3kMQgACjujFyGBOiKbHNXW=-hc=7+G-cE-+y5BDSakg@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit

Andy -- I understood your intent, but thanks for clarifying. (as well as 
taking the time to break this discussion out in the first place). I 
agree with your assessment.

re: Sean's comments, if it wasn't clear by me asking in the first place, 
I also think sticking as close as possible to semver's rules is the best 
approach, although I'm getting the impression that there have been some 
previous reservations to doing so (especially by your comment about 
backporting features if there is demand is).

I've found adhering to the bug-fix release restrictions can be a very 
painful and time-consuming task, so this is something to get a 
representative sampling of those who do the work to make sure everyone 
is on board.

Sean Busbey wrote:
> I'd much rather we stick with the definitions used in Semantic Versioning.
> Our use is already confusing enough given our matrix of compatibilities
> that don't get "major version for breaking" protections.
>
> We've previously discussed how we'll do additional minor releases when
> there's sufficient interest in the new features present there. What's
> building that demand if any backwards compatible change can go back into a
> patch release?
>
> Would we have an easier time restraining ourselves if we had a regular
> schedule planned around new minor versions?
>
>
> On Wed, Apr 22, 2015 at 12:03 PM, Josh Elser<josh.elser@gmail.com>  wrote:
>
>> While I can understand the desire to want to add things, I do think it
>> makes things harder for users to reliably write code against versions of
>> HBase which (by their view) should be completely compatible with one
>> another.
>>
>> Take this extremely hypothetical situation: I'm new to HBase and start
>> writing some code against HBase 1.0.1 which was just deployed at my $job. I
>> don't _know_ what APIs are new, I just know what exists and treat that as
>> acceptable for me to be using. Meanwhile in production, some other people
>> find a bug with HBase 1.0.1 and roll back to 1.0.0 which they had been
>> previously using. My reaction would be "of course my code should work with
>> HBase 1.0.0, I only used the public API" when in fact this is not true.
>>
>> Personally, I think it's a little bold to say semver is even in use if
>> this principal isn't being followed as it doesn't follow at all with my
>> understanding on the guarantees defined by semver for bug-fix releases.
>>
>> That being said, if the intent *is* to allow ourselves to make these sorts
>> of changes, I just think some sort of disclaimer should be present:
>>
>> - HBase uses Semantic Versioning for its release versioning
>> + HBase uses Semantic Versioning for its release versioning with a caveat
>> that methods and members might be added in newer bug-fix releases that were
>> not present in the previous bug-fix release.
>>
>>
>> Andrew Purtell wrote:
>>
>>> [Subject changed]
>>>
>>> On Tue, Apr 21, 2015 at 8:47 PM, Josh Elser<josh.elser@gmail.com>   wrote:
>>>
>>>   I was a little surprised when I noticed method additions to
>>>> InterfaceAudience.Public annotated classes. This means that a user could
>>>> write code against 1.0.1 that would not work against 1.0.0 which seems
>>>> undesirable for a bugfix release. I read over the book section on
>>>> compatibility and didn't see this addressed, so I thought I'd ask.
>>>>
>>>
>>> Let's clarify this. It's not the first time this question has been asked.
>>>
>>> To get things moving:
>>>
>>> I propose the following addition to the "Client API compatibility" section
>>> of Section 11.1:
>>>
>>> + APIs available in a patch version will be available in all later
>>> + patch versions. However, new APIs may be added which will not be
>>> + available in earlier patch versions.
>>>
>>> I propose the following change to the "Client Binary compatibility"
>>> section
>>> of Section 11.1:
>>>
>>> - Old client code can run unchanged (no recompilation needed) against new
>>> jars.
>>> + Client code written to APIs available in a given patch release
>>> + can run unchanged (no recompilation needed) against the new
>>> + jars of later patch versions.
>>>
>>>
>>> What do you think?
>>>
>>> If these changes are (mostly) ok, then this clarifies in one direction.
>>>
>>> If these changes are not acceptable, I will propose edits that clarify
>>> toward the opposite meaning. ​
>>>
>>>
>>>
>
>