> some aspects of the v2 API are clearly downgrades from the v1 API. Please open a JIRA, and we can discuss there. If there's already any discussion, please point to them.
> My big concerns are purely "cosmetic" (HTTP Methods, API paths, HTTP Status Codes, etc). Patches welcome. Or if you open a JIRA, we can discuss there. On Wed, Oct 27, 2021 at 8:57 PM Ishan Chattopadhyaya < [email protected]> wrote: > > 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] >>> >>>
