lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Busch <busch...@gmail.com>
Subject Re: Proposal for changing the backwards-compatibility policy
Date Tue, 16 Jun 2009 15:49:28 GMT
Sounds good, Grant. I'll open a task to change the policy with target 
release=3.0.

  Michael

On 6/16/09 6:53 AM, Grant Ingersoll wrote:
> +1 on everything.  This is the sanity we need, especially #2.   Thanks 
> for bringing this up again.
>
> I'd add a slight mod to #2 that I think helps further communicate to 
> users our expectations (marked by my initials GSI) by employing some 
> convention in our @deprecated comments:
> 2. Deprecated public and protected APIs can be removed if they have
>   been released in at least one major or minor release. E.g. an 3.1
>   API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>   (if 4.0 comes after 3.2).
> GSI: Furthermore, the Deprecation tag comment will state the minimum 
> version when this API is to be removed,  e.g.
> @deprecated See #fooBar().  Will be removed in 3.3
> or
> @deprecated See #fooBar().  Will be removed in 3.3 or later.
>
> Also, while #4 covers breaking Interfaces, it would be nice if we had 
> some way of stating that an interface is going to change, assuming we 
> are thinking about it.  Alternatively, maybe we should just out right 
> label all Interfaces as being subject to change.  For instance, if we 
> want to add to Fieldable, perhaps we could say, in the comments, 
> something like:  We expect to add the following to Fieldable: 
> getWhizBangValue() in version 3.3.  This will break any 
> implementations of Fieldable.  Still, I'm fine with #4 as stated.
>
> Finally, I still think we all agree that when possible, we should make 
> _reasonable_ efforts to maintain back compatibility.
>
> -Grant
>
>
> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>   i.e. Lucene X.Y supports reading all indexes written with Lucene
>>   X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>   indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>>   been released in at least one major or minor release. E.g. an 3.1
>>   API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>   (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>>   if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>>   "Incompatible changes", which lists, as the names says, all changes 
>> that
>>   break backwards compatibility. The list should also have information
>>   about how to convert to the new API. I think the eclipse releases
>>   have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably >2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org


Mime
View raw message