I have been thinking for a while that is time we revisit our back-
compatibility "policy" (http://wiki.apache.org/lucene-java/BackwardsCompatibility
) in terms of maybe becoming a little leaner and also in terms of
addressing some issues that come up from time to time in relation to
bug fixes that effect how Tokens are produced. As examples of the
latter, see: https://issues.apache.org/jira/browse/LUCENE-1084 and https://issues.apache.org/jira/browse/LUCENE-1100
. Examples of the former issue include things like removing
deprecations sooner and the ability to add new methods to interfaces
(both of these are not to be done ad-hoc)
In the case of bugs, the main issue is that people may be expecting
the "incorrect" behavior (admittedly, the maxFieldLength is not
incorrect), so the question becomes should we be in the business of
preserving incorrect values for a full version?
In the case of being "leaner", there are times when it would be useful
to be able to add new methods to interfaces w/o waiting for a full
major release (other projects do this) and also being able to pare
down the deprecated methods sooner.
I propose a couple of solutions to the leaner issue, but I am not sure
how to handle the incorrectness issue, although I suppose it could be
similar. With all of this, I really think the issue comes down to how
we communicate current and future changes to our users.
1. We add a new section to CHANGES for each release, at the top where
we can declare what deprecations will be removed in the _next_ release
(major or minor) and also any interface API changes
2. When deprecating, the @deprecate tag should declare what version it
will be removed in and that version must be one greater than the next
targeted release. That is, if the next release is 2.4, then anything
deprecated in 2.3 is game to be removed in 2.9.
3. Other ways of communicating changes????
My reasoning for this solution: Our minor release cycles are
currently in the 3-6 months range and our major release cycles are in
the 1-1.5 year range. I think giving someone 4-8 (or whatever) months
is more than enough time to prepare for API changes. I am not sure
how this would effect Index changes, but I do think we should KEEP our
current index reading policy where possible. This may mean that some
deprecated items cannot be removed until a major release and I think
that is fine.
Do people think that the bug issue also fits into this way of doing
things? Or do we need another way to think about those?
These are just suggestions and I am interested in hearing more about
what people think. I know, in some sense, it may make us less stable,
but I doubt it given the time frame of our releases. I also know a
perfectly valid response is "If it ain't broke, don't fix it" and to
great extent, I know it ain't broke. And believe me, I am fine with
that. I am just wondering if there is an opportunity to make Lucene
better.
Cheers,
Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
compatibility "policy" (http://wiki.apache.org/lucene-java/BackwardsCompatibility
) in terms of maybe becoming a little leaner and also in terms of
addressing some issues that come up from time to time in relation to
bug fixes that effect how Tokens are produced. As examples of the
latter, see: https://issues.apache.org/jira/browse/LUCENE-1084 and https://issues.apache.org/jira/browse/LUCENE-1100
. Examples of the former issue include things like removing
deprecations sooner and the ability to add new methods to interfaces
(both of these are not to be done ad-hoc)
In the case of bugs, the main issue is that people may be expecting
the "incorrect" behavior (admittedly, the maxFieldLength is not
incorrect), so the question becomes should we be in the business of
preserving incorrect values for a full version?
In the case of being "leaner", there are times when it would be useful
to be able to add new methods to interfaces w/o waiting for a full
major release (other projects do this) and also being able to pare
down the deprecated methods sooner.
I propose a couple of solutions to the leaner issue, but I am not sure
how to handle the incorrectness issue, although I suppose it could be
similar. With all of this, I really think the issue comes down to how
we communicate current and future changes to our users.
1. We add a new section to CHANGES for each release, at the top where
we can declare what deprecations will be removed in the _next_ release
(major or minor) and also any interface API changes
2. When deprecating, the @deprecate tag should declare what version it
will be removed in and that version must be one greater than the next
targeted release. That is, if the next release is 2.4, then anything
deprecated in 2.3 is game to be removed in 2.9.
3. Other ways of communicating changes????
My reasoning for this solution: Our minor release cycles are
currently in the 3-6 months range and our major release cycles are in
the 1-1.5 year range. I think giving someone 4-8 (or whatever) months
is more than enough time to prepare for API changes. I am not sure
how this would effect Index changes, but I do think we should KEEP our
current index reading policy where possible. This may mean that some
deprecated items cannot be removed until a major release and I think
that is fine.
Do people think that the bug issue also fits into this way of doing
things? Or do we need another way to think about those?
These are just suggestions and I am interested in hearing more about
what people think. I know, in some sense, it may make us less stable,
but I doubt it given the time frame of our releases. I also know a
perfectly valid response is "If it ain't broke, don't fix it" and to
great extent, I know it ain't broke. And believe me, I am fine with
that. I am just wondering if there is an opportunity to make Lucene
better.
Cheers,
Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org