[Twisted-Python] INCOMPATIBLE CHANGE: twisted.python.dist renamed to twisted.python._setup

[Craig Rodrigues]

On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>
wrote:

>
> This is also addressing a real problem.  One of the *major* issues with
> Twisted is *documentation noise*.  Developers trying to use Twisted to
> build things frequently complain about this: they look for an API to do
> XYZ, and they search the reference documentation, which produces dozens of
> confusing, irrelevant hits.  There are multiple issues that interact here
> (see, for example, <https://github.com/twisted/pydoctor/issues/49> which
> is a big part of the problem) but one significant one is that our
> apparently-public API surface is just too big.  Removing things like this,
> which are really _totally_ useless to anyone, is useful in and of itself
> and also amplifies the benefit of any other work on docs and tooling to
> properly segregate public and private API documentation.
>
>

Making dist.py private seems to fall under the category of "code
cleanliness", and doesn't
seem to solve any specific pressing issue that I see.  Reducing
documentation noise is a good goal,
but if dist.py was left the way it is, things would probably be OK with
Twisted, and I think people
could figure things out in Twisted with respect to the documentation.

Since you mention pydoctor, I will mention two issues, that I feel are more
important to the project
that moving around dist.py:


   - pydoctor produces false errors, specifically in h2 code:
   https://buildbot.twistedmatrix.com/builders/documentation/builds/1291/steps/api-documentation/logs/pydoctor%20errors
   - pydoctor doesn't work on Python 3:
   https://github.com/twisted/pydoctor/issues/96

I understand that Twisted is a volunteer project, and people can work on
whatever they want.
I also see on this list, that a few people support the dist.py change, so
as long as
Adi's change meets the Twisted coding standards, gets code review approval,
and can pass all the buildbots,
it can move forward, despite my objections.

--
Craig
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160807/e36d491e/attachment-0002.html>