Re: [PATCH] qemu-deprecated: Remove text about Python 2

[John Snow <jsnow@redhat.com>]

On 1/14/20 5:20 AM, Daniel P. Berrangé wrote:
> On Tue, Jan 14, 2020 at 11:08:16AM +0100, Thomas Huth wrote:
>> On 13/01/2020 23.36, John Snow wrote:
>>>
>>>
>>> On 1/9/20 4:51 AM, Thomas Huth wrote:
>>>> Python 2 support has been removed, so we should now also remove
>>>> the announcement text for the deprecation.
>>>>
>>>> Signed-off-by: Thomas Huth <thuth@redhat.com>
>>>
>>> Reviewed-by: John Snow <jsnow@redhat.com>
>>>
>>>> ---
>>>>  qemu-deprecated.texi | 8 --------
>>>>  1 file changed, 8 deletions(-)
>>>>
>>>> diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
>>>> index 7033e531de..8b23e98474 100644
>>>> --- a/qemu-deprecated.texi
>>>> +++ b/qemu-deprecated.texi
>>>> @@ -341,14 +341,6 @@ they have no effect when used with @option{-n} to skip image creation.
>>>>  Silently ignored options can be confusing, so this combination of
>>>>  options will be made an error in future versions.
>>>>  
>>>> -@section Build system
>>>> -
>>>> -@subsection Python 2 support (since 4.1.0)
>>>> -
>>>> -In the future, QEMU will require Python 3 to be available at
>>>> -build time.  Support for Python 2 in scripts shipped with QEMU
>>>> -is deprecated.
>>>> -
>>>>  @section Backwards compatibility
>>>>  
>>>>  @subsection Runnability guarantee of CPU models (since 4.1.0)
>>>>
>>>
>>> Genuine question, I'm sorry:
>>>
>>> Is it worth documenting things we recently removed?
>>
>> Basically yes. In case of Python 2, it's not a QEMU feature that we
>> remove here, but a build requirement, and we tell the users that we need
>> at least Python 3.5 when they run "configure", so I'm not sure whether
>> that needs to be explicitely mentioned again the docs beside our ChangeLog?
> 
> In general changed build pre-requisites such as new minimum software
> versions are documented in the release notes:
> 
>    https://wiki.qemu.org/ChangeLog/5.0#Build_Information
> 
> We normally would not list build pre-requisites in the deprecation notes
> at all, since they don't follow the deprecation process normally. We
> just update minimum versions immediately that our supported OS build
> platforms change due to an OS going end of life. So for example we
> have in the past bumped gnutls, glib, nettle, gcc, etc min versions
> with no warning.  So the fact that Python 2 was mentioned in the
> deprecations at all was slightly unusual. This is mostly just to be
> nice to users since the OS platforms here aren't going EOL and still
> ship Python 2, we simply don't wish to support it any more, since
> the distros also all have Py 3.
> 
> 
>>
>>> Right now, we don't
>>> really have these docs hosted in a searchable way online in a
>>> per-version format. Once the notice is gone, it's gone from the mirror.
>>>
>>> I removed some bitmap functionality not too long ago and I created a
>>> "Recently Removed" section as a bit of a troubleshooting guide should it
>>> be needed.
>>>
>>> - Do we want this section?
>>> - Should I remove it?
>>> - Can we add historical docs to the website to see previous deprecated
>>> docs in a searchable manner?
>>
>> I also once started a page in the Wiki here:
>>
>>  https://wiki.qemu.org/Features/RemovedFeatures
>>
>> ... but apparently, it did not get enough attention yet, otherwise you
>> would have noticed it before introducing the new chapter into the
>> qemu-doc ...
>>
>> We definitely need one spot where we can document removed features. I
>> don't mind which way we do it, either the qemu-doc or the wiki, but we
>> should unify on one of the two. I guess the qemu-doc is the better place
>> since we are tracking the deprecated features there already and one more
>> or less just has to move the text to the other chapter when things get
>> finally removed?
> 
> Yeah, I've said in the past that we should not be deleting deprecations
> from the docs entirely.
> 
> If you look at GTK docs for example, you'll see they keep a record of
> all incompatible or noteworth changes between release:
> 
>   https://developer.gnome.org/gtk3/stable/gtk-migrating-3-x-to-y.html
> 
> IMHO, we should follow this and have an appendix of removed features,
> with sub-sections per QEMU release listing each removed feature. Thus
> deprecation docs just get moved to this appendix at the right time.
> 
> Regards,
> Daniel
> 

Everything said makes sense to me. My review here stands, thanks! (Sorry
for the derail.)

--js