[v3,03/15] python: add VERSION file

Python infrastructure as it exists today is not capable reliably of
single-sourcing a package version from a parent directory. The authors
of pip are working to correct this, but as of today this is not possible
to my knowledge.

The problem is that when using pip to build and install a python
package, it copies files over to a temporary directory and performs its
build there. This loses access to any information in the parent
directory, including git itself.

Further, Python versions have a standard (PEP 440) that may or may not
follow QEMU's versioning. In general, it does; but naturally QEMU does
not follow PEP 440. To avoid any automatically-generated conflict, a
manual version file is preferred.


I am proposing:

- Python tooling follows the QEMU version, indirectly, but with a major
  version of 0 to indicate that the API is not expected to be
  stable. This would mean version 0.5.2.0, 0.5.1.1, 0.5.3.0, etc.

- In the event that a Python package needs to be updated independently
  of the QEMU version, a pre-release alpha version should be preferred,
  but *only* after inclusion to the qemu development or stable branches.

  e.g. 0.5.2.0a1, 0.5.2.0a2, and so on should be preferred prior to
  5.2.0's release.

- The Python core tooling makes absolutely no version compatibility
  checks or constraints. It *may* work with releases of QEMU from the
  past or future, but it is not required to.

  i.e., "qemu.machine" will always remain in lock-step with QEMU.

- We reserve the right to split the qemu package into independently
  versioned subpackages at a later date. This might allow for us to
  begin versioning QMP independently from QEMU at a later date, if
  we so choose.


Implement this versioning scheme by adding a VERSION file and setting it
to 0.5.2.0a1.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 python/VERSION   | 1 +
 python/setup.cfg | 1 +
 2 files changed, 2 insertions(+)
 create mode 100644 python/VERSION

On Tue, Oct 20, 2020 at 03:35:43PM -0400, John Snow wrote:
> Python infrastructure as it exists today is not capable reliably of
> single-sourcing a package version from a parent directory. The authors
> of pip are working to correct this, but as of today this is not possible
> to my knowledge.
> 
> The problem is that when using pip to build and install a python
> package, it copies files over to a temporary directory and performs its
> build there. This loses access to any information in the parent
> directory, including git itself.
> 
> Further, Python versions have a standard (PEP 440) that may or may not
> follow QEMU's versioning. In general, it does; but naturally QEMU does
> not follow PEP 440. To avoid any automatically-generated conflict, a
> manual version file is preferred.
> 
> 
> I am proposing:
> 
> - Python tooling follows the QEMU version, indirectly, but with a major
>   version of 0 to indicate that the API is not expected to be
>   stable. This would mean version 0.5.2.0, 0.5.1.1, 0.5.3.0, etc.
> 
> - In the event that a Python package needs to be updated independently
>   of the QEMU version, a pre-release alpha version should be preferred,
>   but *only* after inclusion to the qemu development or stable branches.
> 
>   e.g. 0.5.2.0a1, 0.5.2.0a2, and so on should be preferred prior to
>   5.2.0's release.
> 
> - The Python core tooling makes absolutely no version compatibility
>   checks or constraints. It *may* work with releases of QEMU from the
>   past or future, but it is not required to.
> 
>   i.e., "qemu.machine" will always remain in lock-step with QEMU.
> 
> - We reserve the right to split the qemu package into independently
>   versioned subpackages at a later date. This might allow for us to
>   begin versioning QMP independently from QEMU at a later date, if
>   we so choose.
> 
> 
> Implement this versioning scheme by adding a VERSION file and setting it
> to 0.5.2.0a1.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>

I'd rather have the version to be sync'd with QEMU, but, I understand
this is a more conservative approach that can maybe evolve into that.

Reviewed-by: Cleber Rosa <crosa@redhat.com>

On 10/28/20 3:51 PM, Cleber Rosa wrote:
> On Tue, Oct 20, 2020 at 03:35:43PM -0400, John Snow wrote:
>> Python infrastructure as it exists today is not capable reliably of
>> single-sourcing a package version from a parent directory. The authors
>> of pip are working to correct this, but as of today this is not possible
>> to my knowledge.
>>
>> The problem is that when using pip to build and install a python
>> package, it copies files over to a temporary directory and performs its
>> build there. This loses access to any information in the parent
>> directory, including git itself.
>>
>> Further, Python versions have a standard (PEP 440) that may or may not
>> follow QEMU's versioning. In general, it does; but naturally QEMU does
>> not follow PEP 440. To avoid any automatically-generated conflict, a
>> manual version file is preferred.
>>
>>
>> I am proposing:
>>
>> - Python tooling follows the QEMU version, indirectly, but with a major
>>    version of 0 to indicate that the API is not expected to be
>>    stable. This would mean version 0.5.2.0, 0.5.1.1, 0.5.3.0, etc.
>>
>> - In the event that a Python package needs to be updated independently
>>    of the QEMU version, a pre-release alpha version should be preferred,
>>    but *only* after inclusion to the qemu development or stable branches.
>>
>>    e.g. 0.5.2.0a1, 0.5.2.0a2, and so on should be preferred prior to
>>    5.2.0's release.
>>
>> - The Python core tooling makes absolutely no version compatibility
>>    checks or constraints. It *may* work with releases of QEMU from the
>>    past or future, but it is not required to.
>>
>>    i.e., "qemu.machine" will always remain in lock-step with QEMU.
>>
>> - We reserve the right to split the qemu package into independently
>>    versioned subpackages at a later date. This might allow for us to
>>    begin versioning QMP independently from QEMU at a later date, if
>>    we so choose.
>>
>>
>> Implement this versioning scheme by adding a VERSION file and setting it
>> to 0.5.2.0a1.
>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
> 
> I'd rather have the version to be sync'd with QEMU, but, I understand
> this is a more conservative approach that can maybe evolve into that.
> 
> Reviewed-by: Cleber Rosa <crosa@redhat.com>
> 

It's definitely me taking the cowardly way out. I did use the exact QEMU 
version in the last spin, because that seemed like the dumbest thing :)

I think qemu.machine would eventually evolve to track the QEMU version 
directly, whereas qemu.qmp would evolve to keep its own independent 
versioning system.

This is just, I guess, one more semantic nudge towards the idea that 
this is really an independent little component. I just want to give it 
some more time in the oven before I declare it truly and genuinely 
supported as its own project. Once it's on PyPI, I am beholden to more 
than the other QEMU contributors. Satisfying both crowds simultaneously 
seems like it will be tough.

--js