lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hoss Man (JIRA)" <>
Subject [jira] Commented: (LUCENE-1698) Change backwards-compatibility policy
Date Thu, 02 Jul 2009 17:49:47 GMT


Hoss Man commented on LUCENE-1698:


(Note: this proposal is remeniscent of Grant's suggestion a while back... )

The concern I have with an approach like this (as compared to the current policy) is that
it removes information from the version number.  Under the current policy, you can look at
any new version Y and be confident about whether it is backwards compatible with some version
X you are currently using -- if the version numbers are different enough then you *may* need
to make changes to use the new version; but if the numbers are similar enough then you *definitely*
should be able to upgrade without changing code.

For people who upgrade regularly (or semi-regularly), it gives them a clear indication of
how much work should be involved in any given upgrade...
   * 4.5.1 -> 4.5.4 ... bug fixes, drop in replacement
   * 4.5.1 -> 4.7.0 ... new features/api, should take a look at them, and be on the lookout
for new deprecations to save time later.
   * 4.5.1 -> 5.0.0 ... major API changes are likely, probably need to modify code, definitely
need to modify code if you haven't been keeping up with the deprecation warnings.

Because of point #2 in the new policy being proposed, users of some version Y will have no
indication whatsoever of how likely it is that they can upgrade to version Z unless they have
been religiously updating to every new minor release and eliminating the use of deprecated
methods in their code.

This could have the adverse effect of discouraging users from upgrading if they haven't been
keeping up with the bleeding edge of releases.


This loss of information that would come from allowing deprecated methods to be removed in
minor releases is one of the reasons that i (half heartedly) suggested moving to a 4 part
version numbers as a way to maintain information in the version number about API compatibility
without conveying any implications of index format incompatibility or scaring people with
"major" version number changes...

But I don't think that's really necessary: Ultimately there isn't anything about this proposal
that would actually change how easy/hard it is to remove APIs or change functionality between
one release and the next -- it just alters what naming convention would be allowed when such
changes take place.  

Currently, users can be (for lack of a better word) "wary" of major version changes (ie: 4.5.1
-> 5.0.0) because they sound like really big releases that might change things in a way
that break their apps.  Consequently, developers are wary of having major releases too often
and instead we try to have lots of minor releases and leave bad/broken APIs deprecated for
a long time and then "batch" up their removal in major releases.  Switching to a policy where
we remove deprecated methods (or change runtime behavior) during minor releases is likely
just going to make any users who have been wary of major releases in the past wary of minor
releases in the future.

We could accomplish the same underlying goal (increase the flexibility in developing Lucene
internals by allowing faster removal of deprecated/broken APIs/functionality that may be in
the way) without changing our current policy (and without losing any compatibility info in
the version numbers) by getting past whatever hangups we may have about what it means to have
a "major" release and start increment the "major" version number whenever necessary to get
the job done.  

If 4.1.0 has run time behavior that we want to change ASAP, then make the next release 5.0.0
-- even if it's only 2 months later.  If 5.0.0 has an API that we realize is completely hamstringing
our ability to make some amazing performance improvements to the internals, then make the
next release be 6.0.0.

Rethinking how we use the use the current compatibility policy can accomplish the same goals
as changing it without impacting our users in any way beyond how tis proposal would impact
them -- the releases would still come out at the same time and have the same changes -- the
only difference would be in what we call them, and those names would actually convey useful

> Change backwards-compatibility policy
> -------------------------------------
>                 Key: LUCENE-1698
>                 URL:
>             Project: Lucene - Java
>          Issue Type: Task
>            Reporter: Michael Busch
>            Assignee: Michael Busch
>            Priority: Minor
>             Fix For: 3.0
> These proposed changes might still change slightly:
> 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. 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.
> I'd suggest to treat a runtime change like an API change (unless it's fixing a bug of
> i.e. giving a warning, providing a switch, switching the default behavior only after
a major 
> or minor release was around that had the warning/switch. 

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message