Re: [Docutils-develop] Release 0.20

[Adam T. <aat...@ou...>]

Dear Günter, Docutils developers,

Sorry for such a long delay in responding!

[snip]

> YES, it is time for a new release.

Great!

[snip]

> Before the actual release, we should decide on the way ahead and update the
> announcments of future changes
> https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes

> front end tools:
>   - Which Docutils version will drop the ``.py`` extension?
> 
>   - Keep/drop less often required ``rst2*`` tools? Which?
> 
>   - announce switch of packaging framework
> 
>   see also https://sourceforge.net/p/docutils/patches/186/
>  
>   Proposal [GM]:
>     - implement in 0.21
>     - keep [rst2html, rst2html4, rst2html5, rst2latex, rst2man,
>             rst2odt, rst2pseudoxml, rst2s5, rst2xetex, rst2xml]

I agree with your proposal: drop in 0.21. I would suggest only keeping
rst2html, rst2html5, rst2latex, rst2man, rst2odt, rst2pseudoxml, and rst2xml,
but this can always be discussed later and should not futher delay the 0.20
release.


> input encoding:
>   - Announce new default "utf-8"?
>     For which Docutils version?
> 
>   - Which Docutils version shall implement the already announced changes?
>     (They are rather a bugfix, make the code simpler, a patch is ready.)
> 
>   see also https://sourceforge.net/p/docutils/patches/194/
>  
>   Proposal [GM]:
>     implement already announced changes in 0.21
>     announce "utf-8" as default for 1.0
>     announce removal of encoding detection for 2.0

I agree with all three of your proposals here.

> install.py
>   - Remove in which Docutils version?
>     (The removal is already announced but without affected version.)
>    
>   Proposal [GM]:
>     Remove in 0.21, announce this now.

Agree to remove in 0.21, announce in 0.20.

 
> * Drop support for older Python versions? (Which?, When?)
> 
>   Typing hints become a lot simpler (e.g. with the "|" operator) in 3.10.0
>  
>   Proposal [GM]
>     Raise requirement to >=3.9 in 0.21, announce now.
>     (This is the default Python3 version in current Debian/stable,
>     the most "conservative" major Linux release.)

Agree to require 3.9 in 0.21, announce in 0.20.

For interest, Sphinx has a policy__ to support:
"all minor versions of Python released in the past 42 months from the ...
release date with a minimum of 3 minor versions of Python"

__ https://www.sphinx-doc.org/en/master/internals/release-process.html#python-version-support-policy


>> * Future of ``core.publish_string()`` API function:
>> 
>>   a) Keep current behaviour ::
>>  
>>       def publish_string(source: Union[bytes, str],
>>                          [...]
>>                          enable_exit_status=False) -> Union[bytes, str]
>>              
>>      as "wart", just improve documentation?
>>              
>>   b) Deprecate ``publish_string()`` and provide new ``publish_str()``
>>      and ``publish_bytes()`` functions?
>>  
>>   c) Return a sub-class of ``str`` with ``__bytes__()`` method that
>>      encodes with ``encoding`` and ``encoding_errors`` set to the
>>      "output_encoding" and "output_encoding_errors" setting values?
>>     
>>      - as "subtly" changed behaviour, or
>>      - with a new function replacing ``publish_string()``
>>        (find a good name!)?
>> 
>>   Proposal [GM]
>>     - explore c)
>>     - remove ``core.publish_bytes()`` before releasing 0.20.

> I prepared a patch for option c) with a new function attribute 'auto_encode
> for `core.publish_string()`. This would allow to keep the name and switch to
> a behaviour matching it (returning a string, not bytes) gradually (by 
> switching the default value and eventually removing the option later). See below.

I am content to go with option (c), but I would want to simultaneously announce
the version where the default would change to ``auto_encode=False`` and the
version where ``publish_string()`` would only support returning ``str``
instances.

I think that it might be possible to implement the new ``auto_encode``
parameter without a custom ``str`` subclass, but unfortunatley I won't have
time until May to properly work on such an implementation.

Otherwise I would support option (b) to add a new ``publish_str()``. I think we
should keep the ``publish_bytes()`` function in either case. 

>> Are there other open issues that should be adressed before the next release?

> * Implement the patch for a configurable include_root?
>   https://sourceforge.net/p/docutils/feature-requests/91/

I think the ``include_root`` change (and others) can be delayed, they are not
requirements for 0.20

Thanks,
Adam