[Twisted-Python] ask not

Sun Apr 30 08:55:30 MDT 2017

Hey Glyph and everyone,

Am 29/04/2017 um 4:02 schrieb Glyph:
> This doesn't mean that I won't be contributing to Twisted at all as part
> of my job (in fact I probably have something coming later this month),
> just that since I no longer work for an infrastructure provider, "open
> source qua open source" is no longer part of the job description.
> 
> As such, I've been contributing to Twisted somewhat less lately, and I
> expect that contribution to further decline at least for a while.
> 
> Rather than this just resulting in an overall decrease in activity, I
> wanted to send an explicit message asking the community for help, to try
> to use this as an opportunity.  In the past, when prominent members of
> the project (myself included) have stepped back, others have stepped in
> to fill the void, and this has often been the catalyst for significant
> community growth.  However, this has always been a slow, organic
> process, because core project members (again, myself included) haven't
> always been clear about when they were going to be active.

That's a sad thing, seeing I was getting used to reading you
_everywhere_. But I highly appreciate your forwardness and specially you
paving the way for your somewhat stepping down!

> So, if you are wondering, "what can I do for Twisted"?
> 
>  1. If you area already a commit member with repo:write, you know what
>     to do.  Get cracking.
>  2. Reply to this message.  Let's get a conversation going.  Maybe
>     someone else has some good ideas.
>  3. Check out https://twisted.reviews.  The one advantage of remaining
>     on Trac (as opposed to moving fully to Github) is that you can see
>     at a glance, by looking at which rows are not greyed out on that
>     report, what tickets that you have the ability to submit an
>     authoritative code review for.  The rule is: external contributors
>     can review stuff submitted by project members.
>  4. Our main hosted machine now supports Docker!  Volunteer for some
>     operational responsibilities, or move more of our infrastructure
>     into containers so that more of the maintenance work can be reliably
>     tested by folks without permissions to access the actual infra.
>      Have a look over at https://github.com/twisted-infra/braid.
>  5. Everyone's favorite owl also seems to have been somewhat more busy
>     with non-Twisted stuff of late: volunteer to be a release manager to
>     keep our pace of releases up!
>  6. Finish porting us to Python 3.  We are very, very
>     close: http://blog.habnab.it/twisted-depgraph/

I _was_ wondering "what can I do for Twisted?"! So I'm shamelessly
applying your number 2 and adding to the list what I have noticed.

Please note: I mean any critiques in the most constructive way and out
of the respect I have for the team and the love I've grown to have for
the framework.

7. Documentation *needs* an update. This goes mainly for everything that
can be found on twistedmatrix.com. And very specifically for the
developer docs. As a symptom: I don't recall having seen any reference
to the "twisted.reviews" domain anywhere! Right now, the project depends
heavily on _a lot_ of implicit knowledge, which is quite frustrating for
newcomers (hi!).

8. The website has to be restructured. Some things _are_ there,
somewhere, documented in some obscure wiki page linked to from some wiki
page three levels deep. As an anecdotal, but surely representative
example: I've spent hours in Twisted's docs and webpage and right now
I'm reading the DocumentationAnalysis page [1] for the first time.
I think the essence expressed in [1] is critical for the future of the
project, yet besides existing and having an email without replies on the
mailing list [2], that's all there is to it.
Stuff like this has to be more prominent!

9. A clear path for Contribution has to be established. Yes, there is
Wiki page dedicated to that but I think it can be improved a lot.
As, again an anecdotal but representative example: I've been trying to
fix #9100 [3] [4] it's an easy one (that's why I picked it), yet even
when reading the documentation for contributors, I missed a few things
that have complicated the process. And here is the thing: I am actively
trying! This basically means, if somebody sees a bug in Twisted that is
easy to fix, they won't. Or they will, it just won't end up reaching
Twisted's trunk.
Moving the load away from core developers starts by making the
contributing process easier for external contributors, with Glyph kind
of gone, this will be even more important (0.8 core contributors less!).
The following is based on the PR for #9100 [4] and  a couple others [5]
[6], from the POV of an external contributor:
- Bug is reported
- Bug is fixed by someone
- PR is made
- Comments are made
- Comments are discussed / implemented
- Stuff works
- PR remains open without further comments.
- External contributor forgets about Twisted and moves on or waits
indefinitely, while they could be fixing more stuff.

This could be because of a lack of active core-developers, which leads
me to:

10. "Project Governance", which has already been indirectly raised by
Glyph this week when presenting Tom Most (welcome, and thanks!).
Who works on twisted? When? Are they active? Partially active? What do
they do? What needs to be worked on? How does Twisted as an organisation
work? All of these are questions that don't seem too important when it
comes to code, but they extremely relevant when it comes to the project
and when it comes to users deciding Twisted over other options.
I explain further: if person A at company X uses Twisted and they have
the feeling, that Core-Developers are overwhelmed, person A could put
pressure in company X to get some of their time going to helping out in
Twisted. But if they don't know this, they can't. And if they knew this,
how would they?
Notice that I said "uses Twisted", Twisted is quite mature and it is
very possible to use it for a long time without hitting bugs. That's why
the health of the project (as opposed to the code) needs to be visible
from the outside, to non Twisted developers (either core or external).

11. Twistedchecker: from what I've been reading in open PRs, right now
it may be doing more harm than good. What's the coding standard?
testAll? test_all? Twistedchecker says something, documentation says
nothing. Core developer says something different. What About newlines?
Same issue. This is also a key point in getting stuff done by non-core
developers; if they can't trust the tools to help them produce a worthy
patch, why bother? As a side question: do core-developers use
twistedchecker? I would have imagined these issues would have resulted
on bug tickets that do not (yet) exist.

12. Bug discussion integration between Github and Trac? Discussion about
bugs is taken place on GitHub. At least about bugs someone is working
on. This makes sense, since the workflow involves a PR and GH makes
reviewing easier, that's where it ends being discussed. Why is this a
problem? Well, anyone who is not familiar with Twisted's development
will judge this from Trac:
- Oldest bug is #50. Open for nearly 16 years.
- There is nearly no discussion on newer bugs.
- Bugs that get closed, have usually no discussion.
- Therefore, users are being neglected.
That's, of course, an exaggeration and over-simplification; but the
point stands for outsiders. Some integration could mitigate that.

That being said, I could help with some things for a few hours a week. I
just... you know, can't.
I guess, since I'm hijacking threads, I might as well go all-in and ask
for Wiki edit permissions to begin with.

PS: This email got so long, my bread was burning in the oven! Sorry
about that, but I hope it is somehow beneficial.

[1]: http://twistedmatrix.com/trac/wiki/DocumentationAnalysis
[2]: http://twistedmatrix.com/pipermail/twisted-python/2005-May/010386.html
[3]: http://twistedmatrix.com/trac/ticket/9100
[4]: https://github.com/twisted/twisted/pull/769
[5]: https://github.com/twisted/twisted/pull/740
[6]: https://github.com/twisted/twisted/pull/747
-- 
Evilham