Background ========== We have plenty of features in libvirt, some of which were designed at a time when the virtualization story was much more straightforward than the multi-architecture, multi-hypervisor, multi-machine world we currently live in and, while we have found ways to keep the APIs chugging along, the result is sometimes somewhat confusing for users and application developers, as well as requiring libvirt developers themselves to spend quite a bit of collective time working around decisions that, in hindsight, turn out to have been less than fortunate. Two concrete examples are considered here: one is the virConnectNumOfDomains() API which, while known to be racy and having non-racy alternatives, can still be used by developers without getting any kind of warning in the process; the other one is the ability to define a domain without specifying the machine type, which is becoming increasingly problematic now with some x86_64 features being limited to q35 and downstreams looking to push for its adoption, as well as being a manifestation of the more general problem of libvirt's default being sometimes too conservative and at odds with the existence of slimmed-down QEMU binaries being built with reducing the total attack surface in mind. Having a proper deprecation story in libvirt would allow us to point users and developers towards the recommended solution in each case, be it using a different API or querying libosinfo for information; after a generous grace period, we could then remove the problematic functionality altogether. This would be a more conservative version of the process we already have in place for dropping support for older QEMU releases, which recently has allowed us to ax massive chunks of effectively dead code and simplify parts of libvirt quite significantly. This series explores one possible approach to the problem and aims to spark project-wide discussion around the topic. Further work ============ * Fix the known issues listed below as well as all not-yet-known issues that will undoubtably surface through discussion :) * Introduce a mechanism to catch use of deprecated APIs at build time, similar to GLib's G_DISABLE_DEPRECATED, to help application developers proactively move off problematic APIs. * Create a formal deprecation policy with well-defined rules and time scales in the spirit of the existing one covering our relationship with QEMU. Know issues =========== * For the more granular (and more interesting) type of deprecation shown in patch 6/7, warnings are not being reported back to the client as expected. I believe this is caused by the RPC code looking for either a failure, in which case the virError is transmitted, or a success, in which case the actual return value is: we'll have to figure out a way for the error to travel across the wire regardless of whether or not the API call was ultimately successful if we want clients to actually receive warnings when non-local drivers are involved. Andrea Bolognani (7): util: Add 'level' argument to virReportErrorHelper() util: Introduce virReportWarning() tools: Print warnings in virsh util: Introduce VIR_ERR_DEPRECATED_FEATURE Deprecate virConnectNumOfDomains() Deprecate missing machine type in virDomainDefineXMLFlags() tools: Force virsh to use deprecated features include/libvirt/virterror.h | 1 + src/access/viraccessdriverpolkit.c | 2 +- src/access/viraccessmanager.c | 2 +- src/conf/domain_conf.c | 11 ++++++++--- src/datatypes.h | 30 ++++++++++++++++++++++++++---- src/libvirt-domain.c | 6 ++++++ src/libvirt.c | 1 + src/util/virbuffer.c | 4 ++-- src/util/virconf.c | 6 ++++-- src/util/virerror.c | 10 +++++++++- src/util/virerror.h | 15 ++++++++++----- src/util/virkeyfile.c | 6 ++++-- src/util/virxml.c | 2 +- tools/virsh-domain-monitor.c | 2 ++ tools/vsh.c | 3 +++ 15 files changed, 79 insertions(+), 22 deletions(-) -- 2.17.1 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
