lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Shai Erera <>
Subject Re: Breaking Java back-compat in Solr
Date Sun, 10 Jan 2016 07:57:26 GMT
As for SOLR-8475, I will commit it to trunk only. But I think that we
should come up w/ concrete annotations in our code, and annotate classes as
we go, to back our back-compat policy. I propose that we add these:

@solr.internal - this is internal API and will change without notice. No
back-compat guarantees.
@solr.experimental - this is a candidate for a new public API, but will
likely change until it stabilizes. No (strong) back-compat guarantees. - while you can use this API, we cannot guarantee strong
back-compat support. Will be on a per-case basis.
@solr.public - this is our public API, standard back-compat policy. Of
course, if something needs break, we'll discuss the case, but otherwise
users who use this API can expect to upgrade minor releases without
re-compiling their code. Immediate candidate is SolrJ.

I also propose that until we tag all classes, we treat "no annotation" as
@solr.internal (except for SolrJ code). That will force us to explicitly
tag classes that we think should at least be @solr.public, since that's the
only annotation that should draw the attention of developers.

If people agree, we can add these annotations to the build.xml, to add
proper text to javadocs.


On Sat, Jan 9, 2016 at 2:15 AM Jack Krupansky <>

> With the talk of 6.0 coming out real soon and not waiting for new work,
> will this 6.0/5.x issue become moot and morph into an issue for 7.0/6.x?
> Settling the criteria for Solr plugin API back-compat still seems urgent,
> but if the SOLR-8475 work can quickly get committed to trunk for 6.0 maybe
> that takes some of the pressure off. Still, I'd prefer that the back-compat
> criteria be settled ASAP.
> -- Jack Krupansky
> On Wed, Jan 6, 2016 at 10:43 AM, Yonik Seeley <> wrote:
>> On Wed, Jan 6, 2016 at 1:03 AM, Anshum Gupta <>
>> wrote:
>> > As I understand, seems like there's reasonable consensus that we will:
>> >
>> > 1. provide strong back-compat for for SolrJ and REST APIs
>> > 2. Strive to maintain but not guarantee *strong* back-compat for Java
>> APIs.
>> I think this actually represents what our current policy already is.
>> The sticking point is perhaps "Strive to maintain" is changing
>> definition to become much more lenient, to the point of being
>> meaningless.
>> Let's look at the issue that spawned this thread:
>>  (Some refactoring to
>> SolrIndexSearcher)
>> The issue is if QueryCommand and QueryResult should be moved out of
>> SolrIndexSearcher in 5.x (essentially a rename), or of that rename
>> should only be in 6.0.  If one's desire for a class rename (of classes
>> that are likely to be used by plugins) overrides #2, I'd argue that
>> means we essentially have no #2 at all.  Or perhaps I'm not grasping
>> why it's really that important to rename those classes.
>> Regarding annotations:
>> Multiple people have suggested annotating classes that should remain
>> back compat.  If we were to do this, wouldn't we want those
>> annotations to cover the classes in question
>> (SolrIndexSearcher,QueryCommand,QueryResult)?  If not, what would they
>> cover and still be useful?
>> -Yonik
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:
>> For additional commands, e-mail:

View raw message