Skip to content

Conversation

@parveensaini
Copy link

Description

This PR adds a concise documentation note clarifying that scoring and ranking behavior can legitimately change across major Lucene versions, even when no index format break occurs.

Motivation

While upgrading a production Solr deployment across multiple Lucene major versions, we encountered ranking differences that were not attributable to index corruption or misconfiguration. Investigation showed these differences stemmed from intentional changes accumulated over major releases (similarity defaults, normalization details, tokenization/scoring refinements, etc.).

Although these changes are expected and documented in individual release notes, it is not always obvious to users performing large version jumps that preserving historical ranking behavior may require explicitly pinning or supplying a custom Similarity.

What this PR adds

  • A short, centralized note highlighting:

    • Scoring is not guaranteed to be stable across major versions
    • Large version jumps can surface accumulated scoring differences
    • Custom Similarity implementations are the appropriate mitigation if strict backward ranking compatibility is required
  • No behavior or API changes

Why documentation (not code)

The underlying behavior is intentional and consistent with Lucene’s evolution model. This PR aims to reduce confusion during major upgrades by making the tradeoff explicit and discoverable.

Scope

  • Documentation-only change
  • No impact on runtime behavior
  • Intended to complement existing CHANGES.txt and migration guidance

@parveensaini parveensaini force-pushed the docs-scoring-migration-note branch from 59ae133 to 44de1d3 Compare January 17, 2026 09:31
@github-actions github-actions bot added this to the 11.0.0 milestone Jan 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant