On Mon, Jun 10, 2024 at 9:39 AM Markus Armbruster <arm...@redhat.com> wrote:
> Daniel P. Berrangé <berra...@redhat.com> writes:
>
> > On Thu, Jun 06, 2024 at 01:22:14PM -0400, John Snow wrote:
> >> On Thu, Jun 6, 2024 at 6:25 AM Victor Toso <victort...@redhat.com>
> wrote:
> >> > On Wed, Jun 05, 2024 at 11:47:53AM GMT, John Snow wrote:
> >> Importantly, old versions of the schema aren't contained *entirely*
> within
> >> the schema. Here's a timeline:
> >>
> >> v0.12.0: QMP first introduced. Events are hardcoded, commands are
> defined
> >> in qemu-monitor.hx. query commands are hard-coded in monitor.c.
> >> v0.14.0: qemu-monitor.hx is forked into qmp-commands.hx and
> hmp-commands.hx
> >> v1.0: First version which features qapi-schema.json; all query commands
> are
> >> qapified but most other commands are not.
> >> v1.1.0: A very large chunk of commands are QAPIfied.
> >> v1.3.0: Most commands are now QAPIfied, but there are 2-3 remaining.
> >> v2.1.0: events are now fully qapified; most are now defined in
> >> qapi/events.json
> >> v2.8.0: The remaining commands are fully qapified; qmp-commands.hx is
> >> removed.
> >
> > v2.8.0 was in Dec 2016 - 7+1/2 years ago.
> >
> > libvirt's min QEMU version is 4.2.0 - Dec 2019
> >
> > Ther are non-libvirt consumers of QEMU, but for them, do we think it is
> > reasonable for a consumer of QAPI *today*, to care about a QEMU version
> > from almost 8 years ago ?
> >
> > IOW, I wonder if the most pragammatic answer to this problem is to simply
> > entirely ignore the problems prior to 2.8.0 - accept that the versioning
> > is inaccurate/incomplete for versions before 2.8.0
>
> I'm in favour. However, I'd prefer honest "Since: at least 2.8.0" to
> "Since: <untrustworthy but irrelevant version <= 2.8.0>".
>
That's certainly fine by me if it's community consensus to do so.
I wouldn't mind a phrasing in our HTML doc output in this way:
"Since: 4.2.0", when it's after the cutoff, or
"Since: at least 2.8.0" when it's at or prior to the cutoff.
However, because I am unreasonable, I do have a pretty accurate history of
everything that happened prior to then anyway, just in case ...!
(I was afraid of the review feedback of when I went to cull such
information from our docs, admittedly...)
Even after 2.8.0, there are many "breaking changes" to the QAPI schema
format itself that requires various hacks and workarounds in the QAPI
generator to be able to parse until at least v6.2.0 or so; things we
definitely don't feel like hacking into the upstream parser and
maintaining/supporting. It's far easier, I think, to compile this
information *once* and store the compiled result into a file we can check
back into the qemu.git tree to serve as historical reference instead.
So, even if we do ignore such older versions, it's still a question of how
we'd like to store and maintain the historical information so we have a
reference for new releases going forward, and what kind of features we'd
like to see such a format support us with.
My list right now is:
- The ability to see at a glance, as a "one-page summary", any changes to
the QMP wire protocol during Release Candidate phase.
- The ability to programmatically determine from the doc generator:
- when any Command or Event was introduced
- when any Command Argument/Return field was introduced (or modified
incompatibly?)
- when any Event member was introduced/modified incompatibly
I've got some prototypes for this, I hope to send some example output soon
when it's more reasonably complete and I don't have to explain the
Work-In-Progress caveats quite as much; however I'm still receptive to
ideas and suggestions about how to organize this data. Right now, I am
using a JSON Schema format for "compiled" data because it has the ability
to describe arbitrarily nested structures, which allows me to strip all
"non-API" information from the compiled schema, such as intermediate type
names which we do not consider API. This allows me to give accurate
version-to-version diff reports regardless of the type factoring on the
developer's side.
I'm not necessarily attached to this idea, but it has been useful in
prototyping for verifying that the rest of my qapihackborg is functioning
correctly, so it can serve as a starting point for critique and discussion,
I think.
(I just chose JSON Schema because it's something I am aware of and know how
to use, and it fit some loose criteria for the hacking I was doing. Maybe
we'll stick with it, maybe we won't. etc.)
--js
