> 1. If we deprecate an API in the 2.1 release, we can remove it in > the next minor release (2.2). Agree. Maybe also this? 1a. If deprecated functionality is trivially implemented with new one, we reserve the right to delete deprecated things right away with appropriate CHANGES note. Sample I: getOmitTF() is deprecated in favor of getOmitTermFrequenciesAndPositions() which is absolutely identical to the former, save for the name getOmitTF is removed, CHANGES.txt contains a line telling the user to do search/replace on his code
Sample II: score(HitCollector, int) is deprecated in favor of score(Collector, int) score(HitCollector, int) is removed, CHANGES.txt contains a line telling the used to wrap his collector with new HitCollectorWrapper() or reimplement > 2. JAR drop-in-ability is only guaranteed on point releases (2.4.1 > is a drop-in replacement to 2.4.0). When switching to a new > minor release (2.1 -> 2.2) likely you'll need to recompile. Agree. > 3. Default settings can change, but if the change is big enough (and > certainly if it will impact what's indexed or how searches find > docs/do scoring), we add a required "actsAsVersion" arg to the > ctor of the affected class. New users get the latest & greatest, > and upgraded users keep their old defaults. What about a default value for actsAs? I mean, if I agree with using Version.LATEST_AND_GREATEST, why do I have to explicitly set it every time? > 4. [Maybe?] Allow certain limited changes that will require source > code changes in your app on upgrading to a new minor release: > adding a new method to an interface, adding a new abstract method > to an abstract class, renaming of deprecated methods. Yahoo! The right to rename deprecated things makes the need to deprecate VS simply remove bearable. One more thing. What about adopting fixed release schedule? I.e. minor releases are done strictly each three/four/six months. Whatever is finished - goes into release, whatever is not - continues rotting as patches in jira. Either this, or my addition to rule #1 has to be made, or we're going to wait for two years before removing something. First year until a minor release that declares deprecation, another year until next minor release that actually removes garbage. -- Kirill Zakharenko/Кирилл Захаренко (ear...@gmail.com) Home / Mobile: +7 (495) 683-567-4 / +7 (903) 5-888-423 ICQ: 104465785 --------------------------------------------------------------------- To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org For additional commands, e-mail: java-dev-h...@lucene.apache.org