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 16:09:09 GMT
Well I'd actually hope that there will be significantly less need to do 
these "tricks" to get around the new policy.

I'll open a JIRA issue and we can use it to work on the exact wording.

  Michael

On 6/16/09 9:03 AM, Mark Miller wrote:
> Right - I'm not saying that the users should trump the devs, just 
> curious what the response will be, if any.
>
> I also think that when we update the back compat policy, there should 
> be wording that stresses where we should use our new powers carefully 
> (eg common API's and such).
>
> And we should update it to be more accurate - we should mention how we 
> have lots of exceptions and experimental API's that we use to get 
> around what is there now. I imagine that will continue to an extent. 
> Our policy should allow our current behavior :)
>
> - Mark
>
> Michael Busch wrote:
>> Fair enough. We certainly want our users to understand our reasons 
>> for these changes, and keep their trust that we're making our best 
>> efforts to keep upgrading as effortless as possible.
>>
>> However, there will always be someone who is not happy with such a 
>> change. But if the vast majority of the users doesn't complain, we 
>> should be good to go.
>>
>> I'll send a mail to java-user soonish.
>>
>>  Michael
>>
>> On 6/16/09 7:01 AM, Mark Miller wrote:
>>> I'd be interested in what the users list has to say.
>>>
>>> With this many +1's, seems reasonable to take it over there.
>>>
>>> - Mark
>>>
>>> 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
>>
>
>


---------------------------------------------------------------------
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