SOLR-13138: deprecate LegacyBM25SimilarityFactory (apache#269)

Author: cpoerschke

solr/core/src/java/org/apache/solr/search/similarities/BM25SimilarityFactory.java

@@ -24,7 +24,8 @@
 /**
  * Factory for BM25Similarity. This is the default similarity since 8.x.
  * If you need the exact same formula as in 6.x and 7.x you should instead look at
- * {@link LegacyBM25SimilarityFactory}
+ * {@link LegacyBM25SimilarityFactory} noting that it is deprecated as of 8.10.0
+ * and will be removed in 9.x.
  * <p>
  * Parameters:
  * <ul>

solr/core/src/java/org/apache/solr/search/similarities/LegacyBM25SimilarityFactory.java

@@ -38,7 +38,10 @@
  * </ul>
  * @lucene.experimental
  * @since 8.0.0
+ *
+ * @deprecated {@link BM25SimilarityFactory} should be used instead
  */
+@Deprecated
 public class LegacyBM25SimilarityFactory extends SimilarityFactory {
     private LegacyBM25Similarity similarity;
 

solr/solr-ref-guide/src/schema-elements.adoc

@@ -152,7 +152,7 @@ One key exception to this is that you may explicitly declare a {solr-javadocs}/c
 
 In the example above `IBSimilarityFactory` (using the Information-Based model) will be used for any fields of type `text_ib`, while `DFRSimilarityFactory` (divergence from random) will be used for any fields of type `text_dfr`, as well as any fields using a type that does not explicitly specify a `<similarity/>`.
 
-If `SchemaSimilarityFactory` is explicitly declared without configuring a `defaultSimFromFieldType`, then `BM25Similarity` is implicitly used as the default for `luceneMatchVersion >= 8.0.0` and otherwise `LegacyBM25Similarity` is used to mimic the same BM25 formula that was the default in those versions.
+If `SchemaSimilarityFactory` is explicitly declared without configuring a `defaultSimFromFieldType`, then `BM25Similarity` is implicitly used as the default for `luceneMatchVersion >= 8.0.0` and otherwise the deprecated `LegacyBM25Similarity` (which will be removed in 9.x) is used to mimic the same BM25 formula that was the default in those versions.
 
-In addition to the various factories mentioned on this page, there are several other similarity implementations that can be used such as the `SweetSpotSimilarityFactory`, `ClassicSimilarityFactory`, `LegacyBM25SimilarityFactory` etc.
+In addition to the various factories mentioned on this page, there are several other similarity implementations that can be used such as the `SweetSpotSimilarityFactory`, `ClassicSimilarityFactory` etc.
 For details, see the Solr Javadocs for the {solr-javadocs}/core/org/apache/solr/schema/SimilarityFactory.html[similarity factories].