Re: [Docutils-develop] Docutils 0.19 Release

[Guenter M. <mi...@us...>]

On 2022-05-23, Adam Turner wrote:
> Would it be possible to make a 0.19 release soon? 

I am in favour. Engelbert?

However, first I'd like to see a solution for the following problem:

There is an emerging consensus, that after 1.0 we want to follow "semantic
versioning": no incompatible changes to the API in minor releases.
https://sourceforge.net/p/docutils/feature-requests/89/

Currently, several incompatible changes and removals are scheduled
for the `minor` releases 1.1, 1.2, and 1.3. 
This was done under the assumption that 1.0 will be released soon
(after 0.18 or 0.19) and following the policy of warnings at least 
two minor releases before the actual change (as in :PEP:`387`).

Alternatives:

a) Postpone the removals and changes to version 2.0.

   +1  No surprises.
   -1  Junk code and use of deprecated "optparse" module in 1.x series.

b) Pre-pone the changes to release 1.0
   (after releases 0.19 and 0.20 to keep the "two minor releases"
   warning period).

   +1  Cleaner code in Docutils 1.0
   -1  Incompatible changes in a "lower" release than currently announced.

c) Keep an exception from `semantic versioning` for the 1.x series.

   +1  Stick to the current announcment.
   -1  Incompatible change in minor release may be unexpected for some
       despite beeing documented.
       ("Special cases aren't special enough to break the rules.")

I currently prefer a) as the alternative with smallest "surprise factor".

* * * 

> Additionally, should we formally announce the intention to switch the
> default `html` to `html5` in the 0.19 RELEASE-NOTES? (currently we note
> that it "may" change, rather than giving any time scale or concrete
> position).

As author of the `html5` writer I abstain from voting on this topic.

Günter