I raised the point as a general concern but I'm quite willing to accept the clear majority opinion. Definitely not anywhere near veto :)
On Thu, Nov 4, 2021 at 3:20 PM Jason Gerlowski <[email protected]> wrote: > Alright, it seems like there's general agreement that we should > designate v2's evolving nature in some way, and that this should allow > us to break backcompat if necessary on v2 going forward. There were > at least 8 voices in favor with the only disagreement being Gus who > expressed concern on the backcompat front but didn't press the point. > (Gus - I don't want to mistake politeness for "not pressing the > point". if I'm underestimating your level of concern and you're at > "veto", just let me know.) > > With that in mind, I think the next steps here should probably be to: > > 1. decide what label or term we want to go with ("evolving"? > "experimental"? "beta"?), and > 2. figure out what the best way to publicize change in policy. > > For (1) my vote is probably still "experimental". If others care > enough to chime in though I'm happy to go with whatever's most > popular. > > Eric expressed some concern that "experimental" implies that v2 might > not get adopted. IMO that implication might not be a bad thing; > Houston is talking about making the APIs more RESTful, Tim wants to > add OpenAPI support, and there were lots of other changes suggested in > this thread alone. I'm sure something called "v2" will be adopted at > some point, but if even some of those projects attract attention "v2" > could look very different from the v2 that users might know today. So > "experimental" seems accurate to me. > > For (2), I imagine it'd be sufficient to (a) mention the policy change > in release notes, and (b) update the ref-guide's "v2-api.adoc" to > cover this in some detail. We could do other things in addition (an > ANNOUNCE email, etc.), but IMO those seem like overkill. Thoughts? > > Best, > > Jason > > On Wed, Nov 3, 2021 at 2:27 PM Timothy Potter <[email protected]> > wrote: > > > > No relation to manning or the author but there's a MEAP book on sale > > about OpenAPI --> > > https://twitter.com/LukasRosenstock/status/1455915170614677507 > > > > On Mon, Nov 1, 2021 at 8:40 AM Jason Gerlowski <[email protected]> > wrote: > > > > > > I don't know OpenAPI well enough to have an opinion on whether it's > > > right for Solr, except to say that if we do want OpenAPI then an > > > "experimental" designation sounds helpful for giving us flexibility to > > > change our APIs as necessary. > > > > > > I recently created SOLR-15734 as an umbrella for tracking and > > > discussion around what all needs to be done to get v2 ready to > > > supplant v1. Just an FYI in case any of you guys create an OpenAPI > > > ticket - seems like a good place to put it under. > > > > > > On Fri, Oct 29, 2021 at 3:17 PM Jan Høydahl <[email protected]> > wrote: > > > > > > > > Agree. Solr too often suffers from “not invented here” syndrome. > > > > > > > > OpenAPI is closer to REST, , i.e. using the http DELETE verb for > deleting resources etc. I think the only selling-point for v2 was that it > allows mixing lots of actions like adding and deleting in the same atomic > request. But if designed carefully we could still allow that as “bulk” > syntax in OpenAPI for the type of APIs where it makes sense, such as > atomically switching an alias. > > > > > > > > Sendt fra min iPad > > > > > > > > 29. okt. 2021 kl. 18:14 skrev Houston Putman < > [email protected]>: > > > > > > > > > > > > I'm definitely +1 on the OpenAPI requirement for v2 going forward. > > > > > > > > On Fri, Oct 29, 2021 at 12:04 PM Timothy Potter < > [email protected]> wrote: > > > >> > > > >> I actually think that should be a hard requirement for the "next" > API > > > >> ... if v2 is so different and awkward compared to a broadly adopted > > > >> standard, I'd say that's a short-coming of the v2 design. If we're > > > >> going to keep rolling out APIs that no standardized tooling > supports, > > > >> just stick with v1, our users are no better off. > > > >> > > > >> On Fri, Oct 29, 2021 at 9:52 AM Eric Pugh > > > >> <[email protected]> wrote: > > > >> > > > > >> > I did try to write a OpenAPI specification for V2, and discovered > how much customization/specifics I would have to do, and gave up because we > were so very different. With the “experimental” tag, we could evolve > towards the OpenAPI spec standards if folks wanted to ;-) > > > >> > > > > >> > On Oct 29, 2021, at 11:48 AM, Timothy Potter < > [email protected]> wrote: > > > >> > > > > >> > Does the v2 API support OpenAPI? I looked over the docs and it > seems > > > >> > like not, which is a shame. OpenAPI > > > >> > (https://swagger.io/specification/) opens up a mature ecosystem > of > > > >> > tooling. The _introspection endpoint seems nice but if automated > tools > > > >> > can't understand it, then our users can't auto-generate SDKs or > > > >> > interact with the API using tools like SwaggerUI, and so on. > > > >> > Once your API is OpenAPI compliant, you don't need to "document" > it, > > > >> > tools will do that for you. > > > >> > > > > >> > I really think adopting this standard should be part of this > > > >> > conversation, otherwise, we're just re-inventing the wheel around > API > > > >> > design and leaving too much heavy-lifting for ourselves. > > > >> > > > > >> > Tim > > > >> > > > > >> > On Thu, Oct 28, 2021 at 11:40 AM Jan Høydahl < > [email protected]> wrote: > > > >> > > > > >> > > > > >> > +1 to experimental (java level). > > > >> > In user facing docs and tutorials, we can encourage use, with > just a minor note somewhere that it may still change. > > > >> > When users report bugs there will always be a workaround — use v1 > until next release.. > > > >> > > > > >> > Jan Høydahl > > > >> > > > > >> > 27. okt. 2021 kl. 23:18 skrev David Smiley <[email protected]>: > > > >> > > > > >> > > > > >> > I agree that *very* few users use V2. Ok I do at work but it's > maybe one API endpoint so whatever. We should free ourselves from the > burdensome constraints of back-compat until V2 is sufficiently ready, > whenever that is. So I agree with labeling it experimental and we can > elaborate on that is the upgrade notes. Some APIs I think are only V2, so > we can clarify that we're not saying the underlying functionality is > experimental. Not only do we have to concern ourselves with > inconveniencing some users, we have to face the reality of our limited dev > resources, and thus not make the prospect of improvements too hard (nor on > potential contributors). > > > >> > > > > >> > > > > >> > > --------------------------------------------------------------------- > > > >> > To unsubscribe, e-mail: [email protected] > > > >> > For additional commands, e-mail: [email protected] > > > >> > > > > >> > > > > >> > > --------------------------------------------------------------------- > > > >> > 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. > > > >> > > > > >> > > > >> > --------------------------------------------------------------------- > > > >> To unsubscribe, e-mail: [email protected] > > > >> For additional commands, e-mail: [email protected] > > > >> > > > > > > --------------------------------------------------------------------- > > > To unsubscribe, e-mail: [email protected] > > > For additional commands, e-mail: [email protected] > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- http://www.needhamsoftware.com (work) http://www.the111shift.com (play)
