You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Michael Busch (JIRA)" <ji...@apache.org> on 2009/06/16 18:15:07 UTC
[jira] Created: (LUCENE-1698) Change backwards-compatibility policy
Change backwards-compatibility policy
-------------------------------------
Key: LUCENE-1698
URL: https://issues.apache.org/jira/browse/LUCENE-1698
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 course),
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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Assigned: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Michael Busch (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael Busch reassigned LUCENE-1698:
-------------------------------------
Assignee: (was: Michael Busch)
:)
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> Project: Lucene - Java
> Issue Type: Task
> Reporter: 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 course),
> 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.
-
If you think it was sent incorrectly contact one of the administrators: https://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Uwe Schindler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12778262#action_12778262 ]
Uwe Schindler commented on LUCENE-1698:
---------------------------------------
This is the last issue blocking 3.0 somehow. Should I remove the fix version, or do we already have some "official" backwards document available somewhere to resolve this?
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> 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 course),
> 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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Mark Miller (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12726590#action_12726590 ]
Mark Miller commented on LUCENE-1698:
-------------------------------------
I agree. I think we have the tools we need, we just need to accelerate our releases if we want to deprecate faster. We could have made 2.4 2.9. We could have released faster with fewer issues.
I also think that its confusing that you could drop in 4.2 over 4.1, but try 4.4 and your out of luck. Major number bumps and nice and intuitive.
I was behind a change in back compat (though I had no idea what change - was waiting for the right one ;) ), basically for the case of defaults for new users - out of the box performance/experience. The version stuff Mike came up with appears to fix that rather nicely without tweaking back compat versioning schemes though. We can just jump numbers faster.
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> 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 course),
> 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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Hoss Man (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12726575#action_12726575 ]
Hoss Man commented on LUCENE-1698:
----------------------------------
-0
(Note: this proposal is remeniscent of Grant's suggestion a while back...
http://www.nabble.com/Back-Compatibility-to14918202.html )
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...
http://www.nabble.com/Re%3A-Back-Compatibility-p15032881.html
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 information.
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> 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 course),
> 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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Michael Busch (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12762329#action_12762329 ]
Michael Busch commented on LUCENE-1698:
---------------------------------------
Now that 2.9 is out and 3.0 is close, I'd like to get back to this one to get to a conclusion.
We had several informal +1s on javadev and a -0 here from Hoss and Mark. So no -1 yet.
I think the final decision should be made with an official vote on java-dev. How does everyone feel about this? Shall we have a vote right away? I think it might be a good idea to get some feedback about this proposal on java-user first? Or we could even wait a month and bring it up in Oakland at the Lucene BOF?
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> 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 course),
> 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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Commented: (LUCENE-1698) Change backwards-compatibility
policy
Posted by "Michael Busch (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1698?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12778268#action_12778268 ]
Michael Busch commented on LUCENE-1698:
---------------------------------------
This doesn't need to block 3.0.
We discussed this on ApacheCon and I was going to write up a new proposal soon.
> Change backwards-compatibility policy
> -------------------------------------
>
> Key: LUCENE-1698
> URL: https://issues.apache.org/jira/browse/LUCENE-1698
> 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 course),
> 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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org