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. @solr.expert - 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. Shai On Sat, Jan 9, 2016 at 2:15 AM Jack Krupansky <[email protected]> wrote: > 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 <[email protected]> wrote: > >> On Wed, Jan 6, 2016 at 1:03 AM, Anshum Gupta <[email protected]> >> 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: >> https://issues.apache.org/jira/browse/SOLR-8475 (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: [email protected] >> For additional commands, e-mail: [email protected] >> >> >
