[libvirt] [RFC 0/7] Warn at runtime when deprecated features are used

[Andrea Bolognani]

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