Change backwards-compatibility policy [LUCENE-1698]
- Dominant language
- Java
- Stars
- 3.6k
- Forks
- 1.4k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 88
Description
These proposed changes might still change slightly:
I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
use different names; just for convenience here...)
1. The file format backwards-compatiblity policy will remain unchanged;
i.e. Lucene X.Y supports reading all indexes written with Lucene
X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
indexes.
2. Deprecated public and protected APIs can be removed if they have
been released in at least one major or minor release. E.g. an 3.1
API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
(if 4.0 comes after 3.2).
3. No public or protected APIs are changed in a bugfix release; except
if a severe bug can't be changed otherwise.
4. Each release will have release notes with a new section
"Incompatible changes", which lists, as the names says, all changes that
break backwards compatibility. The list should also have information
about how to convert to the new API. I think the eclipse releases
have such a release notes section. Furthermore, the Deprecation tag
comment will state the minimum version when this API is to be removed, e.g.
`@deprecated` See #fooBar(). Will be removed in 3.3
or
`@deprecated` See #fooBar(). Will be removed in 3.3 or later.
I'd suggest to treat a runtime change like an API change (unless it's fixing a bug of course),
i.e. giving a warning, providing a switch, switching the default behavior only after a major
or minor release was around that had the warning/switch.
---
Migrated from [LUCENE-1698](https://issues.apache.org/jira/browse/LUCENE-1698) by Michael Busch, updated May 09 2016
Contributor guide
Research direction
Start by reviewing the proposed backwards-compatibility rules in the issue, including file-format support, deprecated API removal, bugfix constraints, incompatible-change release notes, and deprecation wording. Determine whether the project has an existing policy or release-note entry point to update; done requires an agreed policy and documented migration guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend, search
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100