downstream extensions

downstream extensions

[Vladimir Sementsov-Ogievskiy]

Hi all!

We declare a kind of __com.redhat_drive-mirror syntax for downstream extensions of QAPI.

That's inconvenient:

Assume I want to merge now my keep-dirty option for Qcow2 driver "[PATCH v2 0/2] qcow2: add keep-dirty open option" to our downstream. To avoid possible conflicts with upstream in future, I should now call it __com.virtuozzo_keep-dirty. Not saying about this being too awkward, there is a real problem:

I want to support dot-object-notation syntax, i.e. something like

qemu-img check --image-opts driver=qcow2,keep-dirty=true,file.filename=img.qcow2

And this way, a period inside a name looks ambiguous, as it looks like subproperty of "__com" property.

I now tested, it still works somehow, and test from my series passes with

  keep_dirty_opts="driver=qcow2,__com.virtuozzo_keep-dirty=true,file.filename=$TEST_IMG"

But anyway, it looks ambiguous, and I don't want to use it and share with my colleagues.

In past, I used x-vz- prefix for downstream names (before I heard about __RFQDN_ notation declared in QAPI spec), that was more convenient. But still, that is not correct..

I now think to use just __vz_ prefix. Such name will never appear upstream, and unlikely to be used by Rhel downstream which is our base. And I don't care about any other downstreams.


Any thoughts? Should we change the recommendations somehow? I think allowing dots in names in the object model is a bad idea.

-- 
Best regards,
Vladimir

Re: downstream extensions

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:

> Hi all!
>
> We declare a kind of __com.redhat_drive-mirror syntax for downstream extensions of QAPI.
>
> That's inconvenient:
>
> Assume I want to merge now my keep-dirty option for Qcow2 driver "[PATCH v2 0/2] qcow2: add keep-dirty open option" to our downstream. To avoid possible conflicts with upstream in future, I should now call it __com.virtuozzo_keep-dirty. Not saying about this being too awkward, there is a real problem:
>
> I want to support dot-object-notation syntax, i.e. something like
>
> qemu-img check --image-opts driver=qcow2,keep-dirty=true,file.filename=img.qcow2
>
> And this way, a period inside a name looks ambiguous, as it looks like subproperty of "__com" property.

The downstream extension prefix predates dotted keys.  Their combination
is less than ideal, as you point out, but it's not actually ambiguous:

Consider this grammar:

    key               = key-fragment { '.' key-fragment }
    key-fragment      = [ downstream_prefix ] / [^=,.]+ /
    downstream_prefix = '__' rfqdn '_'
    rfqdn             = / [A-Za-z0-9.-] /

When a key-fragment starts with '__', it has a downstream prefix, which
extends to the next '_'.

parse_qapi_name() implements this, and keyval.c uses it.

The grammar in keyval.c neglects to cover the downstream prefix.  I'll
fix it.

> I now tested, it still works somehow, and test from my series passes with
>
>  keep_dirty_opts="driver=qcow2,__com.virtuozzo_keep-dirty=true,file.filename=$TEST_IMG"

qemu-img --image-opts still uses QemuOpts.  I don't remember more about
how it parses dotted keys other than "it's complicated", but downstream
prefixes not working would be a bug.

> But anyway, it looks ambiguous, and I don't want to use it and share with my colleagues.
>
> In past, I used x-vz- prefix for downstream names (before I heard about __RFQDN_ notation declared in QAPI spec), that was more convenient. But still, that is not correct..
>
> I now think to use just __vz_ prefix. Such name will never appear upstream, and unlikely to be used by Rhel downstream which is our base. And I don't care about any other downstreams.
>
>
> Any thoughts? Should we change the recommendations somehow? I think allowing dots in names in the object model is a bad idea.

Maybe, but that boat sailed long ago.

QAPI's downstream prefix was designed this way to let organizations
extend the schema without having to worry about clashes regardless of
how things get rebased or remixed.  That's a feature.

It reuses an existing registry of organization names: domain names.  Not
needing our own registry is also a feature.

Of course, nothing can stop you from putting something other than RFQDN
between __ and _.  I'd recommend not to.

We could add a revised downstream prefix syntax, and deprecate the first
one.  To me, that feels like more trouble and complexity than it's
worth.  I could be wrong.  Happy to read proposals.