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

[Pavel Hrdina]

On Thu, Oct 04, 2018 at 01:16:46PM +0200, Michal Privoznik wrote:
> On 10/04/2018 01:03 PM, Andrea Bolognani wrote:
> > On Wed, 2018-10-03 at 10:44 +0200, Erik Skultety wrote:
> >> On Wed, Oct 03, 2018 at 09:13:00AM +0200, Michal Privoznik wrote:
> >>> On 10/02/2018 05:38 PM, Pavel Hrdina wrote:
> >>>> Definitely agree with Peter, having a runtime warning for issue that
> >>>> you cannot change in runtime situation is IMHO wrong.  Even though we
> >>>> cannot remove any API the deprecation warning can be still useful
> >>>> because it can suggest better API to use instead of the old one.
> >>>
> >>> So two of our biggest consumers use python bindings. I'm failing to see
> >>> how a compile time warning would help here.
> > 
> > The compile time warnings would cause bindings developers to find
> > out APIs are being deprecated as they compile against newer libvirt
> > the same way applications developers linking against the C library
> > would; additionally, they could use that information as a motivation
> > to deprecate *their* APIs in a language-appropriate manner.

I completely agree with this.

> > So, as mentioned elsewhere, I believe we should have ways to warn
> > about deprecated features *both* at compile time and at runtime.

But definitely not with this paragraph. See below.

> >>> In other words, if our goal is to make users switch to newer versions of
> >>> functions then we might have to find a better solution (than compilte
> >>> time warnings). Runtime warnings would work with python though.
> >>
> >> As John's pointed out in his reply, given our API contract, we're providing
> >> devs of apps built on top of libvirt with certain guarantees, so it's fair to
> >> assume they'd just ignore the warnings, since we can't break our contract and
> >> their product keeps working anyway, so "why bother changing it", right?
> >> Unfortunately, I feel it's a common practice not to change anything unless it
> >> stops working and there might even be very legitimate reasons for such a
> >> practice, like simply not enough man power.
> >> Therefore I myself don't see any mass adoption/switch to the new preferred/safe
> >> versions of our APIs any time soon. The only effect you'd IMHO achieve by having
> >> runtime warnings is log pollution. Having said that, I don't have any better
> >> ideas on how we could achieve this brave goal without using the obvious drastic
> >> measures.
> > 
> > Deprecation warnings can still help adoption: if tools start spewing
> > them, users will notice and report bugs, eventually annoying
> > developers into migrating to non-deprecated APIs :)
> 
> This was my reasoning too. We have to have run time warnings. Not all
> languages are compiled. Even though I have no statistics, I am confident
> to say that oVirt and OpenStack are our biggest consumers and they use
> python bindings. Compile time warnings won't help us there, rather the
> opposite - put pressure on us when writing them.

You should not mix libvirt and libvirt-python, two separate projects
and two separate issues.  Even if that is true, we should still handle
deprecation warnings for C code as well and that should be compile time
only.  See bellow.

> > Of course this works better for command line applications like
> > virt-install than for GUI applications like virt-manager, but it's
> > useful nonetheless.
> > 
> > That said, in order to reap real benefits, deprecating features
> > should go hand in hand with having a well-defined support policy
> > that includes a timeline describing how, after a generous grace
> > period, the functionality will actually be dropped altogether.
> > 
> 
> /me grabbing some popcorn and soda O:-)
> 
> So this was going to be my question. What is the end goal we are trying
> to achieve? If it is to advertise we have a better API to do the job, we
> can document it - just like we are doing so far. Also the term "better
> API" depends on individual use case heavily. If I have a small, one host
> virtualization solution, and I know nobody else is starting up/shutting
> down domains, I might use virDomainGetNames() just fine.
> 
> Worse, if I have a working solution and I upgrade libvirt I'll start
> seeing warning all of a sudden. This kind of breaks our promise of
> stability.
> 
> If the goal is to make mgmt apps switch to APIs we consider better, then
> we definitely need runtime warnings. I don't see how apps written in
> dynamic, not compiled languages can detect they're using deprecated API
> without running themselves. And surely nor developers, nor QEs have 100%
> code coverage tests.

Runtime deprecation warning in C code is wrong in my opinion and even
though there are some project doing it we should not do it.
Deprecation warning is for developers, not for users.

Yes, adding deprecation warning into libvirt will not solve the goal for
oVirt nor OpenStack, but this should be handled in the libvirt-python
binding code using language-specific manner as Andrea mentioned above.
In python it happens to be a runtime warning,
warnings.DeprecatedWarning, however, that warning is by default ignored
unless it's triggered from __main__, so developers using libvirt-python
API would need to enable that warning for their test-suite, that's a
python way how to do it.

One of the reasons why it's not enabled by default is that as user
you have no way how to modify the module code and therefore you should
not get the warning.  From user point of view everything works how it
should and I don't care whether my program uses something deprecated 
or not.  It's unnecessary noise for the user.

Again, we should not introduce runtime deprecation warnings in C code.

Pavel

> 
> And for dropping functionality - we can not do that. Period.

+1, for everyone questioning this please read [1], thanks.

Pavel

[1] <https://libvirt.org/support.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20181004/036890c4/attachment-0001.sig>