On Thu, 2018-10-04 at 16:04 +0100, Daniel P. Berrangé wrote: > On Thu, Oct 04, 2018 at 04:49:43PM +0200, Andrea Bolognani wrote: > > I agree that having better documentation would help, and we should > > definitely work towards that goal. > > > > However, I'm fairly confident trying to address issues through > > documentation only will not be enough to get applications off > > problematic API usage: people mentioned several times elsewhere in > > the thread how they think *emitting warnings* itself wouldn't be > > enough, and developers would only take notice once the application > > breaks for good! How is documentation going to be effective? Who > > would look at documentation periodically just to make sure they're > > not using features that have since been deprecated? I know I don't > > do that for any of libvirt's dependencies, but if I started getting > > warnings I'd certainly take notice. > > > > Unless users are nagged about it during usage and developers are > > nagged about it during development, usage of problematic APIs will > > never go away. > > I'm not concerned if usage doesn't go away entirely, because I believe > in our goal to preserve API compatibility indefinitely. I don't see that as a goal per se, but rather as a *mean* to achieve goals such as ensuring applications don't break on users during upgrade and application developers don't have to work harder than necessary to keep up with changes in libvirt. It's not, however, quite a silver bullet because, for all the good it does, it also introduces several issues, some of which have been mentioned in this thread. I believe a better balance would be achieved by guaranteeing *long term* API/ABI stability, in the order of several years, so that application developers and users still benefit from not having changes forced on them too frequently but we also have the chance to clean up after our mistakes from time to time, which again would not only help libvirt developers but also, indirectly, users and application developers too. > If an application > is using an API or feature & it works for them that is fine. Even if the > API has known design flaws, that isn't a problem unless those flaws are > relevant to the usage scenario of the app Usage scenarios can and will change. Someone earlier in the thread used the example of a simple application that works just fine despite using racy APIs because there's only one person starting and stopping guests: what happens when a second admin enters the picture? Now you have to spend time figuring out where the (seldomly occurring) issue comes from and ultimately fix it by switching to the non-racy API. Wouldn't it have been much better if using the racy API had raised warnings from the very beginning, causing the developer to switch to the non-racy one before hitting any issues? Also, circling back to the machine type conundrum, what if the application or deployment assume guests will be i440fx but at some point a QEMU binary with i440fx compiled out is installed on the system? Suddenly what used to work doesn't work anymore despite the application itself sticking to "what works for them". > I'm much more interested in how we can help application developers pick > the most effective approaches to using libvirt, and a couple of lines in > a deprecation message are not effective for this. While a short "this is deprecated" message won't give application developers or users the whole story, it will certainly give them motivation to look up the details in the documentation. > A large part of this thread is based off the fact that apps are blindly > relying on defaults. This is bad because no single default is a good > choice for all scenarios. What's needed is guidance on how to effectively > configure guests using libosinfo to identify suitable choices. This means > explaining to apps how libosinfo fits into the picture when using libvirt, > and describing the caveats around the choices of machine types, or the > choices of CPU models. There's no escaping the writing of detailed docs > to get across these points. Do we expect virsh users to also, unprompted, go out of their way to read documentation targeted at application developers? -- Andrea Bolognani / Red Hat / Virtualization -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
