lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From DM Smith <>
Subject Re: Proposal for changing the backwards-compatibility policy
Date Tue, 16 Jun 2009 17:11:54 GMT
Mark Miller wrote:
> I'm inclined to agree to a large extent. If we want to remove 
> deprecations more often, why not release major versions more often?
> The main ramification I see being that the index back compat period 
> could be significantly shortened time wise with the current policy.
I don't think that there is a requirement that 5.x, or later, *must not* 
be able to read 3.x. It is merely an allowance.

Conversely, the side effect of using minor releases as major ones is 
that we indefinitely postpone the allowable breaking of index 
compatibility. With this proposal, what would ever drive a 4.0 release?

-- DM

> DM Smith wrote:
>> 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.
>> Perhaps you should go back and see why the thread died. The points I 
>> made earlier, at the end of the thread, are still pertinent. I'll 
>> highlight some of that again.
>>> 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.
>> I'll reiterate what this means to me. It is more than just file 
>> format stability. An index must still be useful. An index is 
>> invalidated if the analyzers, filters and/or token streams produce a 
>> different result. If these change, the index is not really readable.
>>> 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).
>> To support #2, in view of #1, we need robust test cases that focus on 
>> input and output of the invariants of analyzers, filters and token 
>> streams. We may already have this.
>> Regarding #1 and #2, I think that bug fixes should not be held back 
>> when it changes these outputs.
>> I'll reiterate here too. This will cause Linux distributions, such as 
>> Debian, to number Lucene differently. This will cause confusion.
>> The Debian policy is to bump the major revision number every time 
>> there is an incompatible API change.
>> This really is not necessary. We already have a sufficient mechanism 
>> to do #2: just do a major release. But it requires frequent releases.
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>>    if a severe bug can't be changed otherwise.
>> Just as important as the signatures, the input/output relationships 
>> should not change, except to fix an undebatable bug.
>>> 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:
For additional commands, e-mail:

View raw message