lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Miller <markrmil...@gmail.com>
Subject Re: Proposal for changing the backwards-compatibility policy
Date Tue, 16 Jun 2009 16:03:34 GMT
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
>


-- 
- Mark

http://www.lucidimagination.com




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