Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
MIME-Version: 1.0
In-Reply-To: <4A3775F4.60306@gmail.com>
References: <4A3775F4.60306@gmail.com>
Date: Tue, 16 Jun 2009 08:07:50 -0400
Message-ID: <9ac0c6aa0906160507vdd9fae4u871e2c4633b4c48d@mail.gmail.com>
Subject: Re: Proposal for changing the backwards-compatibility policy
From: Michael McCandless <lucene@mikemccandless.com>
To: java-dev@lucene.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

+1 to all 4.

Mike

On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<buschmic@gmail.com> 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;
> =A0 i.e. Lucene X.Y supports reading all indexes written with Lucene
> =A0 X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> =A0 indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> =A0 been released in at least one major or minor release. E.g. an 3.1
> =A0 API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> =A0 (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> =A0 if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> =A0 "Incompatible changes", which lists, as the names says, all changes t=
hat
> =A0 break backwards compatibility. The list should also have information
> =A0 about how to convert to the new API. I think the eclipse releases
> =A0 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