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 <ans...@anshumgupta.net> 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
