> While that does mean that users will be hesitant to move to it for the time > being, isn't that kind of the point since we are planning on changing things?
Exactly, that's the point of major release upgrades. Users will remain sceptical of moving production to 9x during the early few releases anyway. Hopefully, we'll fix the APIs during that phase. Towards that, if APIs change a little, that should be alright, in my opinion. We should just do a good job of documenting the changes in release notes. We can *start with all V2 APIs marked experimental in 9.0 and keep unmarking in subsequent minor releases* as parts of it mature. > Why do we want users to use something when it's not ready. For whatever functionality is exposed via V2 APIs, it is ready. There may be bugs that we'll get to know about only once users start using it. If there are critical bugs or gaps that we know of, let us address them now before a 9.0 release. So, here's my thoughts: 1) Make V2 the default in 9x, because unless it is the default, no one will use it. If users are so scared, they can stay with 8x or use the older v1 APIs on 9x. 2) If there are critical gaps in V2, lets treat them as blockers before 9.0. 3) Only 1-2 developers have worked on building these APIs, and just 1-2 committers have worked on documenting these APIs. Let us join forces positively to take this forward and fix all problems (code and documentation), since they are an amazing quality of life improvement for everyone using these APIs. These APIs make Solr look much better than before. On Wed, Oct 27, 2021 at 8:37 PM Houston Putman <[email protected]> wrote: > Personally I think, while it made a lot of improvements, some aspects of > the v2 API are clearly downgrades from the v1 API. > I do think we should move towards deprecating the v1 API, but not until we > have a solid (and documented of course) v2 or v3 API. > > 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. >> > > If we make v2 the default, that means we can't go and make necessary > backwards-incompatible changes along the way. We need to make those changes > first before we go and recommend that people use it. > > I agree that the v2 API should be "experimental", or whatever phrase we > want to use to say that the API might change between minor versions, until > it's in a much better shape. > > While that does mean that users will be hesitant to move to it for the > time being, isn't that kind of the point since we are planning on changing > things? Why do we want users to use something when it's not ready. > I agree that it's harder to improve an API that no one uses, but more > importantly (to me) no one will use an API that breaks on them after > upgrading a minor version, unless they are explicitly told this can happen. > > 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. >> > > 100% agreed here. (Wrote my previous paragraphs before your reply) > > If there were discussions around huge changes... > > > Completely agreed here as well. My big concerns are purely "cosmetic" > (HTTP Methods, API paths, HTTP Status Codes, etc). If we want to start > using protobuf or something like that, then yes a v3 will be required. > > - Houston > > On Wed, Oct 27, 2021 at 11:01 AM Jason Gerlowski <[email protected]> > wrote: > >> > 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] >> >>
