[Lucene-java Wiki] Update of "BackwardsCompatibility" by HossMan

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucene-java Wiki" for change notification.

The following page has been changed by HossMan:
http://wiki.apache.org/lucene-java/BackwardsCompatibility

The comment on the change is:
based on msg A9113C99-32E5-4BBA-940E-3C04767A8B23@apache.org on java-dev@lucene

------------------------------------------------------------------------------
- Lucene version numbers are about compatibility.
+ Backwards Compatibility in Lucene is all about version numbers.
  
- Minor versions should always have complete API back-compatiblity. 
- That's to say, any code developed against X.0 should continue to run 
- without alteration against all X.N releases.  A major release may 
- introduce incompatible API changes.  The transition strategy is to 
- introduce new APIs in release X.N, deprecating old APIs, then remove all 
- deprecated APIs in release X+1.0.
  
+ == APIs and Compilation ==
- File formats are back-compatible between major versions.  Version X.N 
- should be able to read indexes generated by any version after and 
- including version X-1.0, but may-or-may-not be able to read indexes 
- generated by version X-2.N.
  
+ Minor versions should always have complete API back-compatiblity.  That's to say, any code developed against '''X.0''' should continue to run without alteration against all '''X.N''' releases.  
- Note that older releases are never guaranteed to be able to read indexes 
- generated by newer releases.  When this is attempted, a predictable 
- error should be generated.
  
- Taken from an e-mail from Doug Cutting
+ A major release may introduce incompatible API changes.  The transition strategy is to introduce new APIs in release '''X.N''', deprecating old APIs, then remove all deprecated APIs in release '''X+1.0'''.
  
- http://mail-archives.apache.org/mod_mbox/lucene-java-dev/200605.mbox/%3C44622D4D.3080508@apache.org%3E
+ == File Formats ==
  
+ File formats are back-compatible between major versions.  Version '''X.N''' should be able to read indexes generated by any version after and including version '''X-1.0''', but may-or-may-not be able to read indexes generated by version '''X-2.N'''.
+ 
+ '''Note:''' Older releases are never guaranteed to be able to read indexes generated by newer releases.  When this is attempted, a predictable error should be generated.
+ 
+ == Changes to Runtime Behavior ==
+ 
+ From time to time, the Lucene Developers may decide that a particular bug fix or enhancement (which does not require or involve and API change) should result in a change to the default runtime behavior in some Lucene functionality because the "new" behavior is deemed "better" or more "correct" then the existing behavior.  These changes will not necessarily be backwards compatible for some Lucene clients who may have dependencies or expectations on the "old" behavior.
+ 
+ If a runtime behavior change is included in a release, this will be clearly noted in the CHANGES.txt file.
+ 
+ If a runtime behavior change is included in Minor releases (ie: '''X.N''' to '''X.N+1''') then there will be two mechanisms available for people to "force" the old behavior:
+ 
+    1. A JVM system property will be available for clients to set. (this will allow clients to force the old behavior without any code changes)
+    1. A static method will be introduced which client code can call to set some internal state prior to using any Lucene code.  (this will allow clients in environments that do not permit system properties to be set to upgrade by only adding one line of code)
+