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

[Glyph Lefkowitz]

> On Aug 7, 2016, at 5:35 PM, Craig Rodrigues <rodrigc at crodrigues.org> wrote:
> 
> I understand the motivation, but the time to have done this was when dist.py
> was originally reviewed.

It certainly would have been better :-).

> There are real problems in the Twisted code, and in the Twisted infrastructure.

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.

For a long time we were extremely conservative about doing any compatibility-breaking thing, even hypothetically breaking, even within the policy we'd set forth, and I think the result of that is a sprawling API that's incredibly hard to navigate, full of old junk that nobody should ever use.  The slightly more aggressive attitude that has been exemplified by e.g. Amber has been a breath of fresh air when it comes to unburdening ourselves from literal garbage.

So I think that "overburdened public API surface" is one of the largest problems facing Twisted and every little bit we can chip away at it is a real win.  We do have to be super careful of course, we don't want to be chopping off obscure but useful pieces of API that programs were actually using, but that's what the compat policy (and judicious judgement) are for.

> Focusing on something like this instead of those problems seems pointless, gratuitous and of little benefit.

In addition to underplaying the usefulness of maintenance like this, I think this comment belies acceptance of a superficially true falsehood - one that I've often fallen prey to myself - and that is, the idea that volunteer time is fungible.  It isn't.  If the members of a project have problems A, B, C, X, Y, Z in very clear ranked order of importance, and a volunteer ("V") shows up to work on Z, the impulse of the existing members of the project is "but you should really just work on 'A'!".  V doesn't care about A, doesn't want to work on A, and the likely result of telling them they should be working on A is that they will feel bad about not working on A and their fix for Z will go unfinished.

I'm not saying that necessarily applies in its full force here; after all Adi is a member of the project as well.  But one of the corollaries of this realization is that if A were really so important someone would already be working on it :).

We should totally have the ABCXYZ list in case anyone shows up just wondering what would be helpful to work on; but if someone shows up with a solution to Z, we should always try to incorporate it and help them feel motivated about continuing, hopefully up the list towards A of course, but maybe they are going to contribute stuff for M, N, and O that we didn't even realize was a problem.

-glyph

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