Re: [PATCH 0/7] python: create installable package

[John Snow]

On 6/19/20 11:15 AM, Philippe Mathieu-Daudé wrote:
> On 6/17/20 10:27 PM, John Snow wrote:
>>
>>
>> On 6/17/20 3:52 PM, Cleber Rosa wrote:
>>> On Tue, Jun 02, 2020 at 08:15:16PM -0400, John Snow wrote:
> [...]
>>> Are you proposing that we have, say, "python-qemu" version 10, being
>>> the 10th API version, without any regard to the QEMU version
>>> supported?  Or version 10.5.3 would mean 10th API version, intended
>>> to support QEMU 5.3?
>>>
>>
>> I am proposing only that we use semver to track the API version of the
>> SDK itself.
>>
>> So that could be:
>>
>> A) 1.x, 2.x, 3.x (etc) with absolutely no connection to the intended
>> QEMU support version. It either works or it doesn't. It might not work
>> very spectacularly. Major semver bumps indicate a breaking change to the
>> library API.
> 
> Major changes occurs between QEMU releases. If there is no QEMU release,
> it is pointless to release the python-qemu package, right?
> 

There might be fixes to the package that might be worth releasing
out-of-band as point fixes. I don't intend to do this if I can help it,
but I wanted to consider the possibility that unforeseen circumstances
might force our hand.

>>
>> B) 1.5.0.0, 1.5.1.0, 1.5.2.0 (etc) where the major version still
>> describes the API, but the remainder of the version describes the
>> intended target QEMU.
>>
>> Or, we could do:
>>
>> C) 5.0.0, 5.1.0, 5.2.0, etc. where it tracks the QEMU version verbatim,
>> end of story.
> 
> At least it KISS.
> 

Simple at a glance.

I have some concerns about how Python packages are normally specified in
e.g. requirements.txt where there's a habit of saying:

package>=3.0.0, <4.0.0

There is a fairly common belief in the ecosystem that semver is being
used. QEMU does not use semver.

This leads us to a strange development paradigm in-tree where the Python
package can have breaking changes from 5.x to 6.x, which are not
otherwise special releases for QEMU itself.

Combined with our deprecation policy, it means that we start adopting a
policy like:

- Features get deprecated for at least two releases
- But can only be changed for a new "major" release.

That mismatch against the QEMU versioning paradigm does not sound like
KISS to me.

>>
>> I don't like (C) very much, because it violates some prevailing idioms
>> about python package versioning. A or B seem better, but do run us into
>> potential trouble with people having mismatched versions.
> 
> Which is why I prefer (C).
> 

Keep in mind that even though it looks more obvious, it still doesn't
enforce the pairing. Problems with mismatched versions are just as
likely to occur because of misconfigurations with requirements.txt.

I guess my big concerns here are:

1. Using 1:1 QEMU versions (starting at 5.x) might imply API stability
for the package, and I would like to avoid committing to that. We *can*
declare the package as Alpha/Beta in PyPI, but in practice I am not sure
that information is consulted as readily as version numbers are.

2. Python world (Citation Needed?) expects semver. We can ignore that if
we choose; there aren't semver police. What are the consequences of
doing that?

3. No matter what we do, the relationship between the Python package and
the QEMU version is only superficial and isn't enforced anywhere. (And,
I think, shouldn't be enforced.)

>>
>> I'd take A or B. (B) is a little chatty but gives some good information
>> and allows you to pin versions effectively, so I think I'm leaning
>> towards that one right now.
>>
>> Well, whatever we do right now, I think I do really want to make sure we
>> are publishing under 0.x to really give the illustration that we are NOT
>> promising even the illusion of stability right now.
> 

It sounds like Avocado might be one of the biggest users of this, so I'd
like to get some more feedback from Cleber, Wainer, et al.

--js