I would say, SolrJ and REST APIs MUST BE backward compatible between minor versions.
The question is about the internal java APIs. It is impossible to get 100% right on these things. If we can start annotating classes/methods and let users suggest stuff then we should be in a reasonably good situation over an year. As a first step open a ticket and define a process to make a certain API backcompat . may be an annotation or whatever. On Tue, Jan 5, 2016 at 11:19 AM, Anshum Gupta <[email protected]> wrote: > Thanks David, > > I agree with what you've suggested but the bigger question here again is > *which* files do we guarantee back-compat for. I suggest we guarantee > back-compat for SolrJ and REST APIs. For everything else i.e. Java APIs, we > should try and maintain back-compat but there shouldn't be a guarantee and > should be the developer's prerogative else defining what is to be annotated > as "Long term support" and what isn't becomes subject to usage and debate. > > On Tue, Jan 5, 2016 at 10:32 AM, [email protected] > <[email protected]> wrote: >> >> Great topic Anshum. >> >> I’ve been frustrated with the back-compat situation since Lucene/Solr 5 as >> a maintainer of my “SolrTextTagger”. One version of the plugin supports 4.3 >> thru the end of the 4x line, whereas on the 5x side I’ve needed 3 versions >> already (5.0-5,1, 5.2, 5.3+)! Sometimes on the API consumer side there is >> simply a new way compatible with the old way and those don’t bother me much; >> what’s annoying is just flat-out differences that can’t easily be coded >> around without reflection. But in my experience through the SolrTextTagger >> (YMMV), Solr hasn’t been the main offender of such changes — it’s Lucene >> changes (be it removing liveDocs bits to get postings, changing the >> BytesRefAttribute signature, or something I don’t remember now). At least >> twice it was avoidable IMO. Nevertheless, we Solr devs should come up with >> a back-compat policy, a simple document/paragraph perhaps, and save it >> somewhere so we can refer to it. Lets not have to dig through the mailing >> list to know our policy some day in the future when we want to explain it! >> >> I suggest that Solr's *default* policy for any source file (Java API) that >> doesn’t otherwise annotate a back-compat statement is to be permissive to >> changes — developer judgement on how much back-compat makes sense to them. >> I say this because the Solr code base is large and I think a relatively >> small portion of it should aim for stability. Lets take SearchComponent as >> an example. *That* needs to be stable. But does HighlightComponent? I >> really don’t think so; besides, it only has one overridable method defined >> by this class that isn’t inherited. Oddly (IMO) there is a separate >> abstraction SolrHighlighter and I can intuit that it’s this guy that was >> intended to be the abstraction of the Highlighter implementation, not the >> some-what generic HighlightComponent. So arguably SolrHighlighter should be >> stable. DefaultSolrHighlighter is debatable as being stable — it’s a >> specific highlighter but it has a bunch of methods designed to be overridden >> (and I have done so). So I think that’s a judgement call (developer >> prerogative). >> >> Should we apply a back-compat policy statement (either through a simple >> comment or better through a new annotation), I don’t think we should feel >> helpless to strictly abide by it for the entire major version range. We >> might decide that such changes are possible provided it gets at least one +1 >> and no -1 veto from another developer. >> >> Summary: >> * Publish a back-compat policy/approach where we can refer to it easily. >> * The default policy of source files without annotations is the >> developer’s prerogative — no back-compat. >> * Annotate the back-compat Java source files as-such and allow us to break >> back-compat only if voted. >> >> ~ David >> >> On Mon, Jan 4, 2016 at 11:28 AM Anshum Gupta <[email protected]> >> wrote: >>> >>> Hi, >>> >>> I was looking at refactoring code in Solr and it gets really tricky and >>> confusing in terms of what level of back-compat needs to be maintained. >>> Ideally, we should only maintain back-compat at the REST API level. We may >>> annotate a few really important Java APIs where we're guarantee back-compat >>> across minor versions, but we shouldn't certainly be doing that across the >>> board. >>> >>> Thoughts? >>> >>> P.S: I hope this doesn't spin-off into something I fear :) >>> >>> -- >>> Anshum Gupta >> >> -- >> Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker >> LinkedIn: http://linkedin.com/in/davidwsmiley | Book: >> http://www.solrenterprisesearchserver.com > > > > > -- > Anshum Gupta -- ----------------------------------------------------- Noble Paul --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
