> unfortunately it's been released without that moniker for a long time ... we > may need to go v3 if we want to change things since people will > understandably have written code against it.
The idea of breaking "existing v2 users" is definitely a sticking point. But I think there's a strong case that these users are a tiny tiny minority out there: see the past lack of v2 docs, SolrJ support, mailing list traffic or bug reports on v2, etc. And if you accept that, then deciding to rigidly follow backcompat or not comes down to deciding what offers the community as a whole more benefit: maintaining API compatibility to avoid code breaks for this tiny minority, or getting a more polished API over the finish line sooner for use by all. Gus - you're right that we could do a "v3"-type approach here while maintaining backcompat, but I agree with Eric's point that v3 would be a step back in terms of forward progress on getting a new API out. If there were discussions around huge changes (switching to protobuf, removing commonly used APIs, etc.) that step back would be worth it. But for the pretty minor backcompat changes that have been proposed (e.g. renaming params for consistency "configSet" -> "config") - it just seems like overkill. If we're worried about upsetting users, there's lots we can do in terms of signaling any potential changes well in advance via ANNOUNCE emails, ref guide docs, etc. > What if we dropped the term “experimental”, because that implies that the v2 > API might not be actually adopted I think there should be some indicator to users about the quality and guarantees around the v2 API, but I'm not especially attached to "experimental" if it's disliked. That said, maybe we should reach consensus on some of the other questions (i.e. backcompat implications) and then figure out what word/label best conveys things. Jason On Wed, Oct 27, 2021 at 10:34 AM Ishan Chattopadhyaya <[email protected]> wrote: > > > While the v2 has been out for a long time, do we actually have evidence > > that it is widely used and has significant code written against it? > > I don't think anyone uses V2 APIs. No one wants to use undocumented APIs. > > > I worry that deciding to go with v3 it going to prevent any forward progress > > Instead of worrying about v3, I think we should just make v2 the default to > drive up adoption and fix it as we go along. APIs will never improve if no > one uses it. And no one will use it if we don't document it properly. > > > What if we dropped the term “experimental”, because that implies that the > > v2 API might not be actually adopted…. > +1 > > > What if we say “v1 is the Long Term Supported version of the API, and v2 is > > the evolving to be better and better API, monitor the release notes for the > > changes ;-)" > > I would rather that we say v1 is old and crappy and we'll drop support for it > soon. V2 is evolving to be better API, and you're encouraged to use it. > > > > > > On Wed, Oct 27, 2021 at 7:48 PM Eric Pugh <[email protected]> > wrote: >> >> While the v2 has been out for a long time, do we actually have evidence that >> it is widely used and has significant code written against it? >> >> When I look at various components/packages that have been written around >> Solr, I don’t see the v2 API used. For example, Project Blacklight, a UI >> for Solr is solidly on v1. >> >> I worry that deciding to go with v3 it going to prevent any forward >> progress…. Having gone through the effort to document v2 in the Ref Guide, >> I’m not dying to now go and add a v3 for all the examples ;-(. I’d rather >> just update the v2 in place and celebrate the “9.1 has cleaned up the X API, >> come check out the new support for Y” ;-) >> >> What if we dropped the term “experimental”, because that implies that the v2 >> API might not be actually adopted…. >> >> What if we say “v1 is the Long Term Supported version of the API, and v2 is >> the evolving to be better and better API, monitor the release notes for the >> changes ;-)" >> >> >> >> On Oct 27, 2021, at 9:07 AM, Gus Heck <[email protected]> wrote: >> >> And I think v1/v2 should be split into their own servlets leveraging common >> code by calling utilities, or composing with other objects rather than >> inheriting and getting in each other's way. I think v2 could change a lot so >> experimental seems appropriate, but unfortunately it's been released without >> that moniker for a long time... we may need to go v3 if we want to change >> things since people will understandably have written code against it. >> >> On Tue, Oct 26, 2021 at 11:01 PM Alexandre Rafalovitch <[email protected]> >> wrote: >>> >>> I felt that V2's lack of support for defaults was a serious architectural >>> issue that is hard to just close eyes on. >>> >>> Regards, >>> Alex >>> >>> On Tue., Oct. 26, 2021, 3:17 p.m. Eric Pugh, >>> <[email protected]> wrote: >>>> >>>> I’d very much like to see this as well. >>>> >>>> I’ve been thinking that I would look to migrate the Solr Admin to using >>>> the v2 API, and I suspect it will identify any number of gaps/areas of >>>> improvement in the v2 API itself. >>>> >>>> >>>> >>>> >>>> On Oct 26, 2021, at 3:10 PM, Jason Gerlowski <[email protected]> wrote: >>>> >>>> Hi all, >>>> >>>> I'm starting this thread to highlight a subject that came up in the >>>> recent "Solr 9.0 Release Blockers" thread: our v2 API. As a TL;DR, >>>> should the v2 API be considered "experimental"? >>>> >>>> We haven't explicitly called the v2 API experimental up to this point, >>>> but I'd argue that in essence it already is. In previous releases it >>>> was largely undocumented, had little or no SolrJ support, missed >>>> parity with v1 in terms of endpoints and parameters, and wasn't >>>> included in test randomization. It's hard to imagine how someone >>>> could have been using the v2 API nontrivially in our past releases. >>>> >>>> Treating v2 as "experimental" just feels much more like calling a >>>> "spade" a "spade", and sends a more accurate signal to our users. It >>>> would also have practical benefits: experimental code is traditionally >>>> free from backcompat guarantees, so an "experimental" designation >>>> would remove a big impediment for those improving the v2 API. >>>> >>>> Knowingly setting backcompat aside is always scary, and of course, we >>>> don't have any means to know for sure how many users v2 has today. >>>> But if we judge from the few signals we do have, the number must be >>>> very small. e.g. The last user-list email that mentions a v2 API path >>>> is "Atomic update error with JSON handler" from May of 2018! >>>> >>>> Potential backcompat breaks might inconvenience that small set of >>>> users, but that inconvenience would be vastly outweighed by the >>>> benefit to all our users of getting a cleaner, more consistent API out >>>> sooner. >>>> >>>> Anyway, that's my pitch. Would love to hear what people think about the >>>> idea. >>>> >>>> Best, >>>> >>>> Jason >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: [email protected] >>>> For additional commands, e-mail: [email protected] >>>> >>>> >>>> _______________________ >>>> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | >>>> http://www.opensourceconnections.com | My Free/Busy >>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed >>>> This e-mail and all contents, including attachments, is considered to be >>>> Company Confidential unless explicitly stated otherwise, regardless of >>>> whether attachments are marked as such. >>>> >> >> >> -- >> http://www.needhamsoftware.com (work) >> http://www.the111shift.com (play) >> >> >> _______________________ >> Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | >> http://www.opensourceconnections.com | My Free/Busy >> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed >> This e-mail and all contents, including attachments, is considered to be >> Company Confidential unless explicitly stated otherwise, regardless of >> whether attachments are marked as such. >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
