Does our interface compatibility promise cover defaults?

Does our interface compatibility promise cover defaults?

[Markus Armbruster]

From about/deprecated.rst:

    In general features are intended to be supported indefinitely once
    introduced into QEMU. In the event that a feature needs to be removed,
    it will be listed in this section. The feature will remain functional for the
    release in which it was deprecated and one further release. After these two
    releases, the feature is liable to be removed. Deprecated features may also
    generate warnings on the console when QEMU starts up, or if activated via a
    monitor command, however, this is not a mandatory requirement.

This obviously applies to syntax and semantics of our external
interface.

Does it apply to default values there?

If no: does this mean we can change defaults without notice?

If yes: does this mean any change of defaults needs notice in
about/deprecated.rst and the grace period?

Note that changing a default is a silent change, like changing semantics
/ behavior, unlike changing syntax.

Re: Does our interface compatibility promise cover defaults?

[Paolo Bonzini]

On 11/11/25 09:32, Markus Armbruster wrote:
>>From about/deprecated.rst:
> 
>      In general features are intended to be supported indefinitely once
>      introduced into QEMU. In the event that a feature needs to be removed,
>      it will be listed in this section. The feature will remain functional for the
>      release in which it was deprecated and one further release. After these two
>      releases, the feature is liable to be removed. Deprecated features may also
>      generate warnings on the console when QEMU starts up, or if activated via a
>      monitor command, however, this is not a mandatory requirement.
> 
> This obviously applies to syntax and semantics of our external
> interface.
> 
> Does it apply to default values there?
> 
> If no: does this mean we can change defaults without notice?

In some sense, versioned machine types are an example "changing the 
defaults without notice": almost every release of QEMU changes the 
default values for -M pc and -M virt.

But then, while we change the defaults, we provide a way to access the 
old defaults and only remove the old machine types with advance 
notification.

> If yes: does this mean any change of defaults needs notice in
> about/deprecated.rst and the grace period?

Generally speaking I'd say so.  I don't speak much crypto, but the 
latest commit to deprecated.rst (commit d58f9b20c71, "crypto: deprecate 
use of external dh-params.pem file", 2025-11-03) looks like a change of 
defaults.

Paolo

> Note that changing a default is a silent change, like changing semantics
> / behavior, unlike changing syntax.
> 
> 
> 

Re: Does our interface compatibility promise cover defaults?

[Daniel P. Berrangé]

On Tue, Nov 11, 2025 at 09:58:53AM +0100, Paolo Bonzini wrote:
> On 11/11/25 09:32, Markus Armbruster wrote:
> > > From about/deprecated.rst:
> > 
> >      In general features are intended to be supported indefinitely once
> >      introduced into QEMU. In the event that a feature needs to be removed,
> >      it will be listed in this section. The feature will remain functional for the
> >      release in which it was deprecated and one further release. After these two
> >      releases, the feature is liable to be removed. Deprecated features may also
> >      generate warnings on the console when QEMU starts up, or if activated via a
> >      monitor command, however, this is not a mandatory requirement.
> > 
> > This obviously applies to syntax and semantics of our external
> > interface.
> > 
> > Does it apply to default values there?
> > 
> > If no: does this mean we can change defaults without notice?
> 
> In some sense, versioned machine types are an example "changing the defaults
> without notice": almost every release of QEMU changes the default values for
> -M pc and -M virt.
> 
> But then, while we change the defaults, we provide a way to access the old
> defaults and only remove the old machine types with advance notification.

Machine types are a special case because we've explicitly designed &
documented them to have this behaviour of changing on every release,
long before we even had the deprecation policy, while also providing
the versioned machines for back compat. More recently we documented
a formal 6 year lifecycle for version machines.


When it comes to defaults in general, and interaction with the
deprecation policy, IMHO, we need to consider the goal of the
policy.

Essentially we're trying to make it possible for QEMU to drop
legacy technical debt, while avoiding repeated surprises on
users and mgmt apps. The compromise was to give users a min
two releases prior warning of the change coming along in the
future to give them time to adapt.

We still have the tension there between the two parties.

As maintainers of QEMU we'd like scope of that policy to be as
narrow as possible, while as a user of QEMU I'd like the scope
to be broad enough to cover anything that might break the way
I currently consume QEMU.

IOW, I think users would consider that policy to apply to defaults
in general, modulo exceptions like the non-versioned machine types
/ aliases which have been explicitly designed to change.

> > If yes: does this mean any change of defaults needs notice in
> > about/deprecated.rst and the grace period?
> 
> Generally speaking I'd say so.

With our mix of versioned and non-versioned machine types things are
somewhat fuzzier than that.

If the default is related to a piece of virtual hardware that is
*only* capable of be used by a non-versioned machine type, then
we have generally been happy to change it without notice.

For virtual hardware covered bya versioned machine type, then we
change it, but add the back compat.

IOW, anything related to virtual hardware is pretty loose with
defaults and hasn't gone through the deprecation process.


The defaults for stuff that is backend related, however, is much
more in scope of the deprecation policy IMHO.

>                                 I don't speak much crypto, but the latest
> commit to deprecated.rst (commit d58f9b20c71, "crypto: deprecate use of
> external dh-params.pem file", 2025-11-03) looks like a change of defaults.

NB not really a change in defaults. Traditionally, by default, we would
auto-generate Diffie-Hellman parameters at startup by calling a special
GNUTLS API. GNUTLS now auto-generates Diffie-Hellman parameters without
any special API being required. Its approach to generating has changed
to be RFC compliant. So we removed our code to manually auto-generate
DH parameters.

Both before & after, users could optionally override the generated
defaults with an external dh-params.pem file they created themselves.

Since GNUTLS is now RFC compliant for its auto-generated parameters,
there is no longer a compelling reason to allow the external override
so we're deprecating it.

I expect almost no one will be using the external dh-params.pem file.
Even once we remove it nothing breaks - existing deployments continue
working, just silently switching to the RFC compliant DH params, which
should not have any observable behavioural change for an admin.

TL:DR: the commit d58f9b20c71 is removing an opt-in feature, not a
default.



With 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 :|