From: Guenter M. <mi...@us...> - 2017-01-10 20:38:20
|
On 2017-01-02, David Goodger wrote: > On Tue, Dec 27, 2016 at 7:26 AM, Guenter Milde <mi...@us...> wrote: >> On 2016-12-23, Brecht Machiels wrote: >> If the discussion remains at the speed we had with the html5 writer, yes. >> But as David announced a return to active Docutils development, there is >> hope for the better. > But I'm going to fight against a lot of the proposed changes. So my > presence may not make the process any more efficient than my absence > ;-) >>> However, if you're serious about using semver, docutils should already >>> be 1.0.0 since the API (however you define it) has been stable and >>> widely used for many years now. So I would suggest moving to 1.0.0 >>> without further changes, with the exception of a fix for the >>> incompatibility introduced by yours truly. >>> Once your list of suggested changes has been implemented, the version >>> number can jump to 2.0.0. Note that there is nothing special about >>> 1.0.0; it is follows from the semver rules. >> I agree that the "de facto" state would have allowed stepping to 1.x some >> time ago. Still, a step in the "major" number for a maintenance release >> just to "catch up" does not seem necessary to me. I propose to relase a >> fixup 0.13.2 and prepare 1.0 with a clearly stated API and a fixed >> docutils.dtd. > Clearly stated API: What do you propose? Should there be a document > listing every module, class, function, and attributes thereof? No. But, e.g., a statement how to avoid the problem of the last Sphinx incompatibility: A project uses Docutils as library, subclasses writers.html4css1.HTMLTranslator(), overwrites a visit_*() method (that pushes one item to the context stack), does not overwrite the matching depart_*() method. Docutils changes the visit/depart method pair not to use the context stack. The problem can be avoided by: * dummy push/pop of the context stack in the new Docutils version (stable API also for side-effects), or * defensive programming in the "client" program: + always overwrite both visit/depart + if calling the parent visit_*(), also call the parent depart_*(). > Adding things is not an issue. Removing things is. So don't remove > things. We never know what client code may depend on what. Changing > function/method signatures is also an issue. So don't change these in > a backwards incompatible way. Also, clear rules on how to implement backwards incompatible changes (announce time, pre-release ...) would be good. > As for the "cleanup": -1. Better to go 1.0 with what we have now than > to put it off, because that may be a *long* time coming. Better now > than never (or a long time from now), the perfect is the enemy of the > good, etc. > 1.0.0 shall be after 0.13.2 though, because that should just be a > bugfix release. > The benefit of releasing 1.0.0 will be pure psychology & PR. It sends > a signal that the software is at a certain level of maturity, and our > commitment. And it removes the contradiction that version number and documentation say: "the API is experimental" but actual API development stalled long ago and users expect a stable API by now. Günter |