On Thu, Oct 04, 2018 at 04:49:43PM +0200, Andrea Bolognani wrote: > On Thu, 2018-10-04 at 14:13 +0100, Daniel P. Berrangé wrote: > > I think we're largely missing the bigger picture here. Configuring > > guests, and using libvirt APIs in general, can be very complicated. > > > > We provide basic API contract docs, and a crude XML schema reference, > > but this is woefully insufficient. There's very little telling apps > > about the big picture way to configure things / implement tasks. > > > > We're missing a good developer guide where you'd give info to apps > > devs about how to effectively use libvirt, so it is no surprise that > > apps do things that are sub-optimal. Providing better docs to app > > devs would be far more useful than deprecation warnings which have > > minimal contextual guidance. > > 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. 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 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. 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. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
