[Twisted-Python] Refactoring Documentation

2011-01-19 Thread Tom Davis 
I've been using (and threatening to work on) Twisted for a few years now. It
seems like every time I get back into it, I need to dig up old code or
Google queries just to get started. Yesterday, Jean-Paul introduced me to
the trial-tutorial
branch
which
has shed some light on the basics of using trial and testing Twisted
client/server applications in general. Until he mentioned it in IRC, I was
stuck looking at the actual tests for protocols and deciding which parts of
that were generically useful to me. I agreed to finish up that documentation
so that it could finally (four years later) be added to trunk (and more
importantly, twistedmatrix.com). But after thinking about it, I believe the
problem runs much deeper than just the lack of a branch merge.

Reading code to find answers isn't rocket science; I've been programming
long enough to be comfortable doing it. But I probably have to resort to
reading Twisted's code about 8 billion percent more often than any other
codebase. And reading code is a hurdle. Reading through Twisted's
semi-random, 45-point FAQ is a hurdle—and recommending it as a starting
point is unhelpful at best. The core documentation isn't awesome either,
given that it has a tendency to be overly cryptic and link to API
documentation that is often incomplete or generally unhelpful.

As one very basic example, see:
http://twistedmatrix.com/documents/current/core/howto/servers.html. Let's
just review a few things wrong with this page:

   - It's tutorial page #1, but basically tells me I need to read
   howto/plugins.html first if I am writing an "application" (whatever that
   is), as opposed to a "TCP, SSL, and Unix socket server". And it's the wrong
   place for UDP.
   - It attempts to introduce Protocols and Factories—two of Twisted's most
   important concepts—and does neither particularly well. I know that Protocols
   (usually) inherit from t.i.p.Protocol and may be instantiated for a variety
   of reasons and aren't (usually) persistent. I also know that Factories
   instantiate Protocols and give a reference to themselves so protocols can
   "access and modify the persistent configuration". I am told I need to
   implement some interface (or something) to actually listen on a host/port. I
   think.
   - At one point "TCP4ServerEndpoint" is instantiated (but never imported);
   its explanation is left to a digression into the endpoints API, which has
   its own issues. Suffice it to say the document doesn't give me sufficient
   reason to actually use the endpoints API.
   - Later on, we just use reactor.listenTCP()—which our previous digression
   (if bothered to click through and read) claims is not preferable.

By the end of the *servers* tutorial (and after reading some linked
documentation), here's all I *really* know:

   1. Factories create protocols somehow
   2. Protocols have methods like connectionMade, connectionLost, and
   dataReceived to handle events
   3. There are other protocols with other methods. One that I know of,
   anyway.
   4. I may need to write a state machine (???)
   5. I should use an Endpoint or maybe a Service or reactor (but probably
   not!)
   6. I should also use Application for serious business

Moving forward, howto/clients.html duplicates a lot of these things and
fills in some gaps in knowledge while creating more holes. Meanwhile, I
still never wanted to create a QOTD or Echo server.

I think the point has been made. My *real* point, though, is that I love
Twisted. And I'm constantly wishing it was more accessible to newcomers.
Twisted is Python's oldest and most mature event-based networking engine and
despite its decade of existence it remains largely confusing and obscure to
the majority of Python programmers who come upon it. It contains concepts
and standards that are alien to the average Python programmer, but they make
a lot of sense and have a lot more consistency and predictability than the
documentation conveys.

I want to fix that, among other things. And as luck may have it, I like
writing documentation. And I know at least enough Twisted to get the
high-level stuff in order and improve the documentation to the point that
people will keep reading long enough to make sense of the "idea of Twisted"
and be able to implement some basic things and expand upon them later.

There are some things I *do* want to accomplish early on:

   - Make the docs accessible (a lot is hidden and hard to find)
   - Make them more concise and useful to somebody who doesn't want to know
   the 50 different ways to skin every cat (including the ones you should never
   use)
   - Make them introduce and explain Twisted in a way that somebody as dumb
   as me can understand it. This means talking about protocols, factories,
   deferreds, etc. in a way that doesn't require thousands of words of circular
   explanations, digressions, and duplications.
   - Document the different Twisted

Re: [Twisted-Python] Refactoring Documentation

2011-01-20 Thread Tom Davis 
Wow! Okay, so, not being really familiar with the list etiquette combined
with the fact that the topic has digressed a bit, I hope you'll forgive the
non-inline reply here. I want to hit the main points of what everybody said
/ asked, but let it be known that I read all of it!

How can we combine these efforts, or at least keep from working at cross
> purposes?
>
> I see from your link above that you are building your own Sphinx project.
> Perhaps you would be better off working from the results of the Lore2sphinx
> conversion?  Are you modifying existing docs or working from scratch?
>
> Let's get together on this!


Hey Kevin! Glyph and Jean-Paul got me up to speed (somewhat) on the whole
lore2sphinx thing last night—though they were rather unclear as to how close
it is to completion. (which you addressed later in this thread)

I certainly want to combine our efforts as much as possible and I'm not too
worried about working at cross purposes; your main task seems to be
converting the existing documentation while mine is reorganizing, editing,
and standardizing it. I'm sure our paths will start to cross when the lore
conversion is complete and you have a huge Sphinx project ready to be
properly organized and catalogued. My hope is we can then begin the process
of merging the two sides of this coin.

My current plan (which should become a bit more clear throughout this
massive reply) is to start from scratch *but* modify existing documentation
wherever possible. If a piece of documentation fits in a "hole" in the
structure and I can get by with a *mv* and some editing, that's what I'd
like to do—it seems the most pragmatic approach.

So here's what I'm kind of thinking as far as combining efforts:
> 1) I'll continue with the "Project Documentation" conversion, while Tom
> works on the other bits.  Should be fairly easy to combine them, I'm
> thinking.
> 2) Let's leave the "Project Documentation" pretty much as-is for the
> moment, until the Sphinx convo is done.
> 3) I wonder if at least some of the "task-based docs" shouldn't be put into
> the project sections, and then just linked to from the task-based section?


This. Point of fact, (3) is already implemented; that example task simply
links to *projects/web/tasks/serve*. This strikes me as the most logical
layout as the tasks are all specific to a particular project (the only iffy
one being Core which is sort of a few projects plus the foundation)—we just
want to highlight some of them.

On to Glyph's reply...

There are many outstanding documentation branches which are substantial
> improvements, which need to be edited and merged - the trial tutorial among
> them.  It would be great if your efforts could start with getting those
> landed, turning the crank on the process to get our users better
> documentation in the interim, as you survey the existing documentation.


I definitely agree that resolving the low-hanging fruit first is a good
idea. For finishing "docs branch X" to make sense, my personal belief is
that X should:

   - Still be relevant in terms of best practices and simply what's
   available
   - If project documentation, have outstanding issues that a passing
   familiarity with the project [right now] will be sufficient to close them (I
   could spend time learning one project, or the same time improving *all* the
   documentation)
   - Adhere to whatever documentation standards we agree upon, if much is to
   left to do.

I guess my overall opinion here is that, yes, if relatively minor edits can
bring a branch close enough to completion that we can get it out there to
help newcomers *now*, let's do that. If a branch is more of a draft and
requires a good deal of fleshing out (or is simply stale), it's probably
worth nailing down the structure and previously mentioned docs standards
before I just create more work for myself (or others) down the road.

Finally, my biggest hurdle right now is not knowing how to *find* said
branches. I don't see "documentation" as a category in Trac and common
keyword searches didn't show up much for me. I'm sure this is an easy
question to answer, though.

What *should* a newcomer who reads this document know by the end of it?


I'm not sure because I can't see how a practical guide to creating something
so generic really fits in the grand scheme of things. I think if you want to
create a TCP server from scratch you must first create the Universe! In this
case, that means learning how Twisted addresses the *concept* of a server
before ever bothering to write one so generic. My general beef is that many
documents seem to make an attempt to appeal to everybody and in doing so
don't sufficiently help anybody. Maybe I can justify that claim better with
examples of "better" (at least more targeted) documents.

A massive pile of improved documentation would of course be useful, but a
> good start would be a clear statement of requirements and audience.  (As
> well as an enumeration of*different* audiences t

Re: [Twisted-Python] Refactoring Documentation

2011-01-21 Thread Tom Davis 
On Fri, Jan 21, 2011 at 5:35 PM, Glyph Lefkowitz wrote:

>
> On Jan 21, 2011, at 8:29 AM, exar...@twistedmatrix.com wrote:
>
> I don't think it makes sense to put anything on Launchpad for now.
> Eventually it needs to go into the canonical Twisted repository, but if
> it's easier to leave it in GitHub for now, that's fine.
>
>
> The only reason I even suggested Launchpad in the first place was to
> suggest a place where you could immediately stick a branch of the Twisted
> tree proper without having commit access, so that you could experiment
> within that tree.  ('bzr get lp:twisted').  I don't believe we have a mirror
> on github, but maybe somebody could correct me.
>
> As long as we're all on the same page as far as the eventual target of
> these docs (i.e. in the Twisted tree, part of some official structure) then
> please feel free to use whatever tools make that easier for you, your
> existing github repo included.
>

We are definitely on the same page. I never wanted the new documentation to
remain separate from Twisted proper. It should be part of the main
repository, build process, etc.


>
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Refactoring Documentation

2011-01-22 Thread Tom Davis 
On Fri, Jan 21, 2011 at 10:00 PM, Glyph Lefkowitz
wrote:

> On Jan 20, 2011, at 11:20 PM, Tom Davis wrote:
>
> I definitely agree that resolving the low-hanging fruit first is a good
> idea. For finishing "docs branch X" to make sense, my personal belief is
> that X should:
>
>- Still be relevant in terms of best practices and simply what's
>available
>- If project documentation, have outstanding issues that a passing
>familiarity with the project [right now] will be sufficient to close them 
> (I
>could spend time learning one project, or the same time improving *all* the
>documentation)
>- Adhere to whatever documentation standards we agree upon, if much is
>to left to do.
>
> I guess my overall opinion here is that, yes, if relatively minor edits can
> bring a branch close enough to completion that we can get it out there to
> help newcomers *now*, let's do that. If a branch is more of a draft and
> requires a good deal of fleshing out (or is simply stale), it's probably
> worth nailing down the structure and previously mentioned docs standards
> before I just create more work for myself (or others) down the road.
>
>
> If branches that are out there *don't* meet these standards, commenting on
> their tickets and getting them deleted or closed as invalid (as appropriate)
> would be a big help too.  Lots of languishing tickets that nobody knows what
> to do with is not a good thing, and there's plenty of opportunities for
> interested parties to reopen tickets, attach new patches, and object in
> various ways, so you shouldn't be too concerned about stepping on toes.
>  Focus is a valuable commodity.
>

I was wondering to what extent it would be helpful to actually reply to all
the tickets, or just the ones that seem to have actionable next steps. I
will try to find something to ask or opine on in each of the documentation
tickets so we can get them moving along or removed.

Part of my comment about low-hanging fruit was to help you get familiar with
> and integrated into the development process.  Going through the process of
> getting patches reviewed and accepted will be _much_ easier if you go
> through the motions of doing a few trivial things first.  In fact you may
> want to just pick up a couple of trivial non-docs patches as well, which
> might help you on documenting the development process :). <
> bit.ly/easy-twisted-tickets> might help you there.
>

I will find an easy ticket or few to bang out. I just replied here (
http://twistedmatrix.com/trac/ticket/2491) in an attempt to get started on
one that doesn't already have a long history.

After spending about an hour going over the "easy" tickets, it seems many of
them are in odd states. Either they're done and waiting on something
undefined or there is an incomplete debate in the comments or the owner
disappeared or... well, there are lots of examples. Maybe this is just me
being dense or whatever, but I think (at least as a newcomer) I could
mass-update all these tickets with "Guidance!" and it would more often than
not be a relevant comment given the state of the ticket.

Here's a great example of what I'm talking about (and I apologize for the
mid-message digression, but I think it's relevant...):
http://twistedmatrix.com/trac/ticket/4636. This seems totally trivial, but
five months later __all__ was never changed in t.i.main and JP's buildbot
link is broken. Whether the offending class should be removed from __all__
or imported instead was never even mentioned. Anyway, I took a stab at it
and attached a trivial patch so this isn't just another complaint (and it
looks like JP closed it while I was drafting this email, so that's great!).
But I do agree that working tickets would really help document the process!


> Mostly, I really don't want you to write a gigantic pile of new
> documentation and then find, when you're "done", that you missed some nuance
> of the coding standard, or the patch is too big to be reasonably reviewed,
> and that now you have three months of additional work to do before it's all
> *really* done.  Experience with the process will mitigate that problem
> significantly.  (And in fact I hope that you don't actually have a gigantic
> pile of stuff to commit all at once at any point, and can continue this work
> incrementally as a series of small tickets, but I realize that later on some
> of the index reorganization stuff may need to be big.  This is mostly just
> restating what Kevin already said in his message, but it bears repeating.)
>

The more I think about this, the more I agree with you. My initial
inclination was just to start from scratch and move over existing docs that
I found I could use.

[Twisted-Python] Fingering Finger

2011-01-22 Thread Tom Davis 
In this thread, I hope to find a resolution to the issue of the Finger
tutorial and efforts to sufficiently improve it or remove it.

In the course of reviewing documentation-related tickets, I stumbled upon
#1148 (http://twistedmatrix.com/trac/ticket/1148). Therein, Glyph first(?)
put down a lot of things we've been discussing and agreeing upon in the
Refactoring Documentation thread. One of the issues still up for debate is
whether or not the Finger tutorial is sufficiently strong to survive the
documentation overhaul. There are various points against it right now:

   - It isn't tested or even test*able*
   - It doesn't cover "best practices" as they relate to writing testable,
   maintainable code, etc.
   - It attempts to implement basically every main Twisted concept, often in
   contrived or poorly-executed ways
   - It has been said it has, "...at best, the potential for mediocrity."

There are also enough tickets related to refactoring / rewriting it that a
resolution would make a significant dent in the list of stale documentation
tickets. Among these two year-old tickets are:

   - http://twistedmatrix.com/trac/ticket/532 - Big jump from finger18.py to
   finger19.py in tutorial
   - http://twistedmatrix.com/trac/ticket/626 - Split tutorial finger code
   into libraries
   - http://twistedmatrix.com/trac/ticket/2205 - Documentation codelistings
   need updating and tests

This shouldn't be a blocker on anything Kevin and I are doing, but it'd be
nice to concurrently have discussions on issues we'll need to address later.
I'm also pretty anal about ticket lists and if these aren't going anywhere
I'd love to close them ;)


Cheers,

Tom
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Weekly Bug Summary

2011-01-22 Thread Tom Davis 
>
> Mean open ticket age: 1032 days

Mean time between ticket creation and ticket resolution: 238 days

Mean time spent in review: 83 days


Wow. Adding "reduce these by at least one order of magnitude" to my todo
list. Gotta have goals!

On Sun, Jan 23, 2011 at 12:05 AM,  wrote:

>  Bug summary
> __
> Summary for 2011-01-16 through 2011-01-23
>   Opened Closed  Total Change
> Enhancements:  3  6690 -3
> Defects:   6  8547 -2
> Tasks: 2  7 65 -5
> Regressions:   0  1  1 -1
> Total:11 22   1303-11
>
> |== Type Changes   |== Priority Changes   |== Component Changes
> |Defect:   -2  |High:+1   |Conch:   -1
> |Enhancement:  -3  |Normal:  -4   |Core:-3
> |Regression:   -1  |Low: -5   |Mail:-3
> |Task: -5  |Lowest:  -3   |Release Management:  -1
>   |Trial:   +0
>   |Web: -1
>   |Words:   -2
>
>
> Total TicketsOpen Tickets
>
>
> New / Reopened Bugs
> __
> = High =
> [#4810] XMPPClientFactory eating away "subscribe" stanzas. (opened by 
> magicblaze)
> defect  words  http://twistedmatrix.com/trac/ticket/4810
>
> = Normal =
> [#4809] usage.Options should handle error messages in a consistent and 
> user-friendly way (opened by tpratt)
> enhancement core   http://twistedmatrix.com/trac/ticket/4809
>
> [#4811] @unittest.expectedFailure decorator breaks trial (opened by ivank)
> defect  trial  http://twistedmatrix.com/trac/ticket/4811
>
> [#4813] provide permissions accessor for filepath (opened by cyli)
> enhancement core   http://twistedmatrix.com/trac/ticket/4813
>
> [#4814] HTTPClient doesn't handle servers that use \n separators instead of 
> \r\n (opened by jasonjwwilliams) (CLOSED, duplicate)
> defect  webhttp://twistedmatrix.com/trac/ticket/4814
>
> [#4816] twistd --uid without --gid breaks (opened by thobbs) (CLOSED, 
> duplicate)
> defect  core   http://twistedmatrix.com/trac/ticket/4816
>
> [#4817] IPv4Address and UNIXAddress not-equal comparison is broken (opened by 
> ivank)
> defect  core   http://twistedmatrix.com/trac/ticket/4817
>
> [#4818] Determine standard structure of Howtos or "Tasks" (opened by binjured)
> taskcore   http://twistedmatrix.com/trac/ticket/4818
>
> [#4712] Missing bits of statinfo accessors in FilePath (opened by cyli) 
> (CLOSED, fixed)
> enhancement core   http://twistedmatrix.com/trac/ticket/4712
>
> = Low =
> [#3372] deprecate --extra option to trial (opened by exarkun) (CLOSED, fixed)
> tasktrial  http://twistedmatrix.com/trac/ticket/3372
>
>
>
> Closed Bugs
> __
> = Normal =
> [#4054] Delete all of the out-of-date mumbo jumbo from the "im" howto (opened 
> by exarkun, closed by thijs, fixed)
> defect  words  http://twistedmatrix.com/trac/ticket/4054
>
> [#4773] The core howto index should link to the endpoints howto (opened by 
> exarkun, closed by cyli, fixed)
> enhancement core   http://twistedmatrix.com/trac/ticket/4773
>
> [#4738] ckeygen man page has wrong summary and synopsis (opened by exarkun, 
> closed by cyli, fixed)
> defect  conch  http://twistedmatrix.com/trac/ticket/4738
>
> [#4740] Use strcred for `twistd mail` authentication options (opened by 
> exarkun, closed by cyli, fixed)
> enhancement mail   http://twistedmatrix.com/trac/ticket/4740
>
> [#4712] Missing bits of statinfo accessors in FilePath (opened by cyli, 
> closed by cyli, fixed)
> enhancement core   http://twistedmatrix.com/trac/ticket/4712
>
> [#4786] twcgi duplicate header (opened by lvh, closed by tenth, fixed)
> regression  webhttp://twistedmatrix.com/trac/ticket/4786
>
> [#4042] [Documentation] It is too hard to figure out how to do trivial 
> common-case sending email with twisted.mail (opened by arkanes, closed by 
> thijs, fixed)
> taskmail   http://twistedmatrix.com/trac/ticket/4042
>
> [#3412] Include link to IMAP Server Tester in Twisted IMAP documentation 
> (opened by biny, closed by thijs, wontfix)
> taskmail   http://twistedmatrix.com/trac/ticket/3412
>
> [#4491] Release Twisted 10.0.1 (opened by exarkun, closed by thijs, invalid)
> taskrelease management 
> http://twistedmatrix.com/trac/ticket/4491
>
> [#4814] HTTPClient doesn't handle servers that use \n separators in

Re: [Twisted-Python] Refactoring Documentation

2011-01-22 Thread Tom Davis 
On Sat, Jan 22, 2011 at 10:02 PM, Glyph Lefkowitz
wrote:

>
> On Jan 22, 2011, at 3:18 PM, Tom Davis wrote:
>
> On Fri, Jan 21, 2011 at 10:00 PM, Glyph Lefkowitz  > wrote:
>
>> On Jan 20, 2011, at 11:20 PM, Tom Davis wrote:
>>
>> If branches that are out there *don't* meet these standards, commenting
>> on their tickets and getting them deleted or closed as invalid (as
>> appropriate) would be a big help too.  Lots of languishing tickets that
>> nobody knows what to do with is not a good thing, and there's plenty of
>> opportunities for interested parties to reopen tickets, attach new patches,
>> and object in various ways, so you shouldn't be too concerned about stepping
>> on toes.  Focus is a valuable commodity.
>>
>
> I was wondering to what extent it would be helpful to actually reply to all
> the tickets, or just the ones that seem to have actionable next steps. I
> will try to find something to ask or opine on in each of the documentation
> tickets so we can get them moving along or removed.
>
>
> Getting rid of dead tickets is almost as important as actually getting
> valid tickets moved along.  I think this effort will be hugely valuable.
>

Will continue commenting on tickets and asserting non-existent power to get
them resolved! ;)


>
> Part of my comment about low-hanging fruit was to help you get familiar
>> with and integrated into the development process.  Going through the process
>> of getting patches reviewed and accepted will be _much_ easier if you go
>> through the motions of doing a few trivial things first.  In fact you may
>> want to just pick up a couple of trivial non-docs patches as well, which
>> might help you on documenting the development process :). <
>> bit.ly/easy-twisted-tickets> might help you there.
>>
>
> I will find an easy ticket or few to bang out. I just replied here (
> http://twistedmatrix.com/trac/ticket/2491) in an attempt to get started on
> one that doesn't already have a long history.
>
> After spending about an hour going over the "easy" tickets, it seems many
> of them are in odd states. Either they're done and waiting on something
> undefined or there is an incomplete debate in the comments or the owner
> disappeared or... well, there are lots of examples. Maybe this is just me
> being dense or whatever, but I think (at least as a newcomer) I could
> mass-update all these tickets with "Guidance!" and it would more often than
> not be a relevant comment given the state of the ticket.
>
>
> No, this is not you being dense.  At least among the core developers in
> Boston, this is a widely-recognized and frequently-complained-about problem,
> and it's something I'd like everyone doing ticket reviews to please think
> about.
>
> Reviewers: if you make a comment on a ticket, but you don't say what you
> want to happen next, then you have effectively killed progress on that
> ticket until some other reviewer comes along and contradicts you to get
> things moving again.  This is especially true if you make one trivial
> comment on the ticket and remove the review keyword, but don't say "please
> address these issues and then merge" or "please address these issues and
> then resubmit for review".  If you've done a partial review, and made a
> comment like "I don't like this aspect of the design" or "please update
> copyright dates" or "your docstring formatting is wrong", please note in
> your comment that this is not a complete review, and *don't* remove the
> review keyword.  Removing the keyword will introduce additional latency for
> the contributor, when other reviewers might still come along and attach more
> comprehensive feedback.  There are few things more discouraging than having
> one free weekend every six months to work on a ticket, and to come back
> every time to "oops, you forgot to update the copyright date and insert a
> blank line in one file of your 300-line patch".
>
> So, Tom: mass updating those tickets wouldn't be helpful, but an update
> every couple of days with a specific question on one of these
> I-don't-know-what-to-do tickets would be great.  Your question on
> tm.tl/2491 was a definite step forward.
>

Awesome! I'm sure a lot of this has to do with the fact that once you
maintain and work on something like this for a decade you take a lot for
granted, especially with regard to your own policies and procedures. It
becomes tedious to provide (or just difficult to enumerate) all the details
necessary to new people. Hopefully as I become more familiar with them I can
ensure some of the tedious/forg

Re: [Twisted-Python] HTTPClient handling LF only servers

2011-01-25 Thread Tom Davis 
On Tue, Jan 25, 2011 at 2:23 PM, Kevin Horn  wrote:

> On Tue, Jan 25, 2011 at 11:54 AM, Jason J. W. Williams <
> jasonjwwilli...@gmail.com> wrote:
>
>> Hi Y'all,
>>
>>
> Howdy, Jason!
>
>
>
>> Certain servers (notably Hacker News) break HTTPClient because they use LF
>> instead of CRLF to terminate header lines. I've uploaded a patch with tests
>> to ticket 4814 (merged into ticket 2842).
>>
>> I'd appreciate a review and some discussion about integrating it.
>>
>> -J
>>
>>
> I'm not really in a position to do a review right now, but since:
>
> 1) 4814 is effectively a duplicate of 2842
> 2) 4814 has a clear problem decription
> 3) 4814 has a patch
> 4) 2842 is old, and confusing


> Can we go ahead and close 2842 in favor of 4814?  We have too many old
> tickets floating around...
>
> (To be clear, I'm not asking Jason to close this ticket...I'm asking for
> the list's opinion)
>

I most certainly agree that 4814 is the more relevant, actionable ticket.
2842 is marred in now-useless history and requires reading through 13
comments just to get to the current point of the ticket as the summary and
description give no indication of it.

4814 is more like a new building constructed on top of 2842's rubble.


>
> Also 3833 is at least similar, if not another duplicate.  It would be nice
> if it could be worked on and/or closed along with this issue.
>

Agreed about 3833. Who cares about finding sites that do/don't send LF? I
could talk about how naively-implemented the whole HN stack is all day, but
it wouldn't get us closer to a resolution for Twisted's web client(s). If
the RFC recommends it for "Tolerant Applications", the only decision is
whether or not we implement that part of the RFC. If it requires more time
to discuss than to actually fix, that means we should probably just fix it
and be done with it.


>
> Kevin Horn
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] HTTPClient handling LF only servers

2011-01-26 Thread Tom Davis 
On Wed, Jan 26, 2011 at 1:39 PM,  wrote:

> On 06:28 pm, gl...@twistedmatrix.com wrote:
> >
> >On Jan 25, 2011, at 6:09 PM, Kevin Horn wrote:
> >>Well, I can update the summary, but not the description, which is the
> >>really bad part.
> >
> >The description _is_ mutable, just only by certain magical people.
> >(For the purpose of spam protection).
> >
> >For now, please feel free to attach a comment to any confusing ticket
> >asking for a description update from someone who can do that; we should
> >do this more often as the foci of various tickets shift.  In the near
> >future hopefully a trac admin (maybe me) will have enough time to more
> >effectively curate the group of magical accounts and their attendant
> >powers so that more people (especially documentation wonks like you and
> >Tom) have that ability.
>
> I've added Kevin and Tom to the group who can do this.  If someone would
> like to volunteer for the job of putting trusted people into this group,
> let me know.
>

Thanks, I can now more efficiently exercise my obsessive compulsions!


>
> Jean-Paul
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Using SerialPort with t.a.s.Application

2011-01-28 Thread Tom Davis 
On Fri, Jan 28, 2011 at 10:38 AM, Kevin Horn  wrote:

>
>
> On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <
> ita...@itamarst.org> wrote:
>
>>
>> A service is supposed
>> to be something you can start and stop, and encapsulates a
>> self-contained piece of business logic.
>>
>> -Itamar
>>
>>
>>
> This or something very much like it should be in the Twisted Glossary.
>

I'd love to see concise, human-readable explanations for all of Twisted's
concepts! It's on the list, anyway...


>
> Kevin Horn
>
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] Task-based documentation started

2011-01-31 Thread Tom Davis 
I have the beginnings of some task-based documentation available in
twisted-docs (https://github.com/tdavis/twisted-docs) now. You can find the
built version in the usual place (http://docs.recursivedream.com/twisted/)
-- just remember to bust the cache.

I chose serving web content as a starting point because it seems as common a
task as any. I took some examples from the existing howto (
http://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html),
as well as added some examples of further learning and glossary entries to
make the point. Obviously there's nothing completely usable here yet; it's
primarily an exercise in showing how I'd like to split up sprawling,
semi-random docs like *using-twistedweb* into more coherent, digestible,
stackable pieces. A document to talk about core concepts (Site Objects,
Resources, etc.), sections for supplementary features like Sessions, Virtual
Hosts, etc.

Another advantage of this style is that we can effortlessly stitch together
our own tutorials (were that ever a goal) just by linking in step-wise
fashion to ever-advanced tutorials which themselves wrap back around to core
concepts like, in this case, Applications and the IService stack. It should
be up to the user how deep into the rabbit hole they want to go; right now I
have to slog through two sections to get to a part that tells me how to just
serve a directory of HTML.

Thoughts?
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Task-based documentation started

2011-01-31 Thread Tom Davis 
On Mon, Jan 31, 2011 at 5:22 PM, Glyph Lefkowitz wrote:

>
> On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:
>
> Thoughts?
>
>
> I'll have to write more later, but maybe you should read *all* of the
> existing twisted.web documentation first?  I am sorry to say it, but this
> seems like a less informative and more confusing version of <
> http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-content.html>
> and <
> http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/wsgi.html>.
>
>
It is certainly less informative than those. I borrowed what I did from the
larger "using twisted.web" document just to illustrate some intent. It is by
no means finished or necessarily representative of the actual content of
those sections (static files and wsgi).


> For example: Why are you talking about SimpleHTTPServer?  Does *anybody* 
> actually
> use that or know about it any more?  I haven't heard it brought up in years.
>  For people who do know about what it is, comparing it to that makes it
> sound like twisted.web is a toy and should not be used in production, since
> SimpleHTTPServer certainly isn't capable of serving a real site.
>

Fair enough.


>
> Again, the problem is not really the content, we have a surprising amount
> of content, it's fixing the architecture so that people *find* the content
> that they're looking for.
>

Right, I agree. I'm not saying content *is* the problem. The problem is both
discoverability from the standpoint of ToC, orphaned pages, etc. *and* from
the per-document standpoint. What one really wants to *do* is often mixed in
with the details of how you could do *everything* related to that one task.
Or it's duplicated. Or in a random file elsewhere.

Perhaps it's best to say that you could consider the text in that tutorial
to be the equivalent of "Lorem Ipsum", except context-relevant enough to get
across the general idea of splitting things up by task, complexity, and
level of existing knowledge (or desired future knowledge).

Take <
http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-content.html
>:

Tell me the one command I need to serve a directory, *then* show me the code
that one command effectively runs and vaguely what it does. Then tell me
where I can learn about twistd and reactors and Sites and Files. And take
that chunk of [usage -> implementation -> further understanding] and call it
a Task (or sub-Task in the case of serving static files).

The content is already there; it's just about arranging it properly. I hope
that helps clear up my opinion a bit.


>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Task-based documentation started

2011-02-01 Thread Tom Davis 
On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl
wrote:

> On Mon, Jan 31, 2011 at 02:41:38PM -0500, Tom Davis wrote:
> > Thoughts?
>
> I think that the overview in the first two sections is very good. It
> made me curious to learn more.
>
> The "breadcrumbs" on the main page look like this:
> "Contents   ::   Serving on the Web — HTML, CGI, WSGI, etc.  » "
> Might be a problem with the Sphinx configuration.
>

Yeah, this is just how the Sphinx template lays things out and it's the
default one I use for documentation on my site, merely because the color
scheme is similar. It's definitely not the greatest and a Twisted-theme one
already exists so we'll be working from that.


>
> Not sure about the link "read more about Twisted": There _is_ more about
> Twisted on the rest of the page. When I clicked the link, I expected to
> be redirected to twistedmatrix.com or something like this. Maybe you
> don't need a link at this position at all.
>

Well, that was originally going to lead to some history/about stuff, but
looking at it again that doesn't seem like an initially great use of time.


>
> In the "Why Use Twisted" section, you write "Framework" - not sure if
> this should be uppercased. But there are some other nouns (Tasks,
> Project Documentation) that are written this way, so maybe it's Your
> Way Of Emphasizing Things ;-).
>
> I'm also not sure if the explanation why I would use Twisted should be
> in bold letters. Everywhere else you use italics.
>
> Do you intend to create a task description for connecting to an SSH
> server (maybe with certificates)? This is something that whould have
> been handy for me in the past.
>

Either create or expose one that already exists, yes.


>
> The "Everything Else" section should not contain links that are already
> presented somewhere else.
>

These are ToC trees which are different from inline links. I don't feel
there's much harm in linking to something twice on one page especially when
the same words are used and one of the uses is clearly a ToC.


>
> Do you intend to add some links to external pages here (e.g. the API
> documentation or other web pages describing how to use the framework)?
> Or should this documentation be self-contained?
>

API links will be common and will be under some reference/links area, I'm
sure. It is very much a work in progress.


>
> One small usability quirk: The presentation of links in an orange, bold
> font does not have much recognition value. I think it would be better to
> use the standard way of marking links by using a blue, underlined font.
> The same goes for links that have already been visited.
>

Again, this is a Sphinx template issue so we'll see how it changes with the
actual Twisted one :)

Thanks for the feedback!

-Tom


>
> Best regards,
>
> Albert
> --
> Albert Brandl
> Weiermayer Solutions GmbH  | Abteistraße 12, A-4813 Altmünster
> phone: +43 (0) 720 70 30 14| fax: +43 (0) 7612 20 3 56
> web: http://www.weiermayer.com
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Task-based documentation started

2011-02-01 Thread Tom Davis 
On Mon, Jan 31, 2011 at 6:19 PM,  wrote:

> On 10:39 pm, t...@recursivedream.com wrote:
> >
> >Take <
> >http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static-
> >content.html
> >>:
> >
> >Tell me the one command I need to serve a directory, *then* show me the
> >code
> >that one command effectively runs and vaguely what it does.
>
> I think this is partially a disagreement over what tasks we actually
> want to document.  If the command line interface gets primacy in the
> documentation, then I think you're writing documentation for end users
> (sys admins, non-programmers).  I don't know about anyone else, but this
> category of documentation hadn't really crossed my mind before.
>
> I think that (ultimately) this is good documentation to have, but I
> don't know if it's as important as getting the programmer-oriented
> documentation in better shape.
>
> Another point to consider is that "twistd web" (and most other twistd
> plugins we provide) are semi-random mish mashes of functionality.  They
> have accreted by contribution from many different people over the years
> with no governing design or goal aside from "expose features from the
> command line".  This does not make them the friendliest tools around.
> The functionality they are missing is often surprising, particularly
> when contrasted with some of the (non-)functionality they do provide.
>
> I don't want to say that they do not bear documenting until their state
> is improved, but if we focused on other areas first, maybe we would have
> something better to document when we eventually get around to things
> like "twistd web".
>

I look at it from a pragmatic point of view: If the task is called "serving
HTML" and you *can* do that with a single command line argument, I'm willing
to possibly waste a sentence exposing something unideal or incomplete if it
fixes the visitor's problem *right now*. That's simply not a lot of effort
 for a good deal of gain. Immediately after that command line section should
be a dive into the actual code (or at least enough to get serving via a
python file).

I suppose you may disagree with task-based views entirely. The using
twisted.web "howto" isn't really one at all. It covers many / all of the
serving aspects of twisted.web which is cool and necessary, but the actual
building block tasks are buried.

It's still early and I'm not sure how much sense I'm making here. I think a
more complete example of what I'm talking about could serve to remedy a lot
of these issues and show that what everybody wants (and already has) is
still present, just moved to a more logical place.


>
> Jean-Paul
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Task-based documentation started

2011-02-01 Thread Tom Davis 
On Tue, Feb 1, 2011 at 12:58 PM, Glyph Lefkowitz wrote:

>
> On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:
>
> Thoughts?
>
>
> Priority #1 for most people who are enthusiastic about documentation is to
> come in and write a ton of additional documentation.  But this is a lot like
> trying to fix a large, broken, untested system by writing a pile of new,
> untested code, because "this time we'll get the design right".  What were
> the problems with the way the previous documentation got written?  How did
> we end up with this mess, and what is going to be done differently this
> time?  Most importantly, *what is the metric by which we will judge this
> new documentation to be better?*
>

Those tutorials aren't new at all; they were taken (often verbatim) from the
"using twisted.web" document. Writing a ton of new documentation really
isn't my goal at all. My goals are threefold:

   1. Reorganize existing documentation in a way that makes it more
   accessible.
   2. Edit existing documentation to conform to a task (howto/tutorial/etc.)
   vs. expanded learning model. (the whole instant gratification thing and all
   that)
   3. Gradually update / replace code listings with "current best practices"
   examples that are tested.

I know you want an actual *layout* for the reorganization. I want to give
that to you, but it requires going through all the documentation and making
sure it fits in the reorganized layout or making sections for it when it
doesn't which is far more time consuming than providing a layout for the
"task" piece, as I did here. I'm basically just saying "How-tos should have
a standard layout with these sections; here's a stub of one such how-to as
incompletely adapted from the current documentation".

I think most of this is a huge misunderstanding as to my goals both in
general and for the particular section critiqued here. Perhaps I should have
completed it before putting it up for review. I just felt it was better to
get *something* out here just in case everybody hated the entire direction
rather than spend a ton of time slicing the current web server docs the way
I personally feel they should fit together in order to properly serve the
audience.


>
> If all that comes out of your efforts is a new, different pile of
> documentation, that's not *entirely* without value; different audiences
> understand things in different ways, so someone might pick it up and
> understand Twisted as a result.  But I very much doubt that's going to move
> us from a general impression of "bad docs" to a general impression of "good
> docs".
>
> More specific criticism:
>
>
>- "This is a Twisted Task"?  I feel like I'm about to start reading
>about a Task object or something related to the twisted.internet.task
>module.  Or maybe that this is an exercise.  A document explaining how to 
> do
>a task is rarely called a "task" itself.  Mostly they're called "How-To"s,
>actually.  I understand you're trying to get away from old terminology but
>this seems awkward and forced.
>
> I just started using this terminology because it seemed common within our
conversations. How-to/tutorial would likely be less confusing.

>
>- "You should be familiar with Resources"?  That is really broad and
>wide-ranging and should be a hyperlink to another tutorial.
>
> It was just a placeholder; it should link to a section in the web server
overview docs that talks about Resources. There are other things on that
list, too (Site object, yada yada). Although, like I said, it's merely
incomplete.


>
>-  Plus, I think that most people interested in these tasks will want
>to learn about how to get simple tasks done first, before moving on to a
>more abstract / theoretical understanding of the model behind them.
>
> I completely agree. That's my whole point with starting off using *twistd*,
despite its limitations or whatever.

>
>- More importantly: this is a very wishy-washy definition of the
>audience.  Is it for system administrators?  Software developers?  DevOps
>people?  Graphic designers?  Power users?  What level of experience do they
>need with Python?  With networking?  With HTTP?
>
> The latter should all be under "Prerequisites" whereas "audience" should
probably be a new howto standard section that's currently overlooked
(perhaps above "Prerequisites"?)

>
>- "Other configuration options are available"?  This should be a list
>of links to other documents that might help with some of those options.
> Documentation which says "and then you could do something el

Re: [Twisted-Python] Task-based documentation started

2011-02-06 Thread Tom Davis 
On Tue, Feb 1, 2011 at 5:15 PM, Glyph Lefkowitz wrote:

>
> On Feb 1, 2011, at 10:53 AM, Tom Davis wrote:
>
> On Tue, Feb 1, 2011 at 12:58 PM, Glyph Lefkowitz 
> wrote:
>
>>
>> On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:
>>
>> Thoughts?
>>
>>
>> Priority #1 for most people who are enthusiastic about documentation is to
>> come in and write a ton of additional documentation.  But this is a lot like
>> trying to fix a large, broken, untested system by writing a pile of new,
>> untested code, because "this time we'll get the design right".  What were
>> the problems with the way the previous documentation got written?  How did
>> we end up with this mess, and what is going to be done differently this
>> time?  Most importantly, *what is the metric by which we will judge this
>> new documentation to be better?*
>>
>
> I'm still really interested in concise answer to that last question there.
>  What are the priorities for what you're trying to improve?  What you've
> listed here is "the steps you're going to take in order to improve it" but I
> have yet to see a lucid description of the problem in detail.
>

I think the problem is largely one of organization (as it relates to
"accessibility", e.g. how / under what context do I get linked to such and
such thing?) and outdated documentation. I think the individual problems are
all very well-known and while there is not some overarching problem with all
the documentation that requires starting from scratch, reorganizing and
restructuring what's there may make it look like I'm trying to do that.


>
> Those tutorials aren't new at all; they were taken (often verbatim) from
> the "using twisted.web" document. Writing a ton of new documentation really
> isn't my goal at all. My goals are threefold:
>
>1. Reorganize existing documentation in a way that makes it more
>accessible.
>
> Accessible to whom?  How will reorganizing it make it more accessible?  One
> way to interpret this statement is that your goal is to remove all diagrams,
> because the documentation is currently not accessible to the blind.  I'm
> pretty sure *that's* not what you mean, but it's a good example of how
> ambiguous this statement is :).  (Plus, the couple of blind developers I've
> talked to about Twisted didn't seem to have a problem with the docs...)
>
>
>1. Edit existing documentation to conform to a task
>(howto/tutorial/etc.) vs. expanded learning model. (the whole instant
>gratification thing and all that)
>
> OK, I'm on board with that.  Except that in order to understand the
> tutorial documentation you need a good backing of reference docs, so it's
> not like you can just choose one over the other.  And we have lots of
> tutorial docs (c.f. the infamous finger tutorial) which are in the tutorial
> / task-oriented paradigm but don't teach much that's directly useful.
>

Finger is a really bad example of what a howto should be; it doesn't teach
you how to achieve some specific, common goal quickly and easily. The names
howto <http://twistedmatrix.com/documents/current/names/howto/names.html>is
a good example of a howto that tells me exactly how to do something in as
few steps as humanly possible. It could use a reference to wherever all the
functions (SOA, A, NS, etc.) are coming from and links to some follow-up
documentation of the *names* project in general, but I digress.

>
>1. Gradually update / replace code listings with "current best
>practices" examples that are tested.
>
> No arguing with that at all, that sounds great.
>
> I know you want an actual *layout* for the reorganization.
>
>
> Not really.
>
> What I want is a clear understanding of what you intend to change.  I
> usually get that by reading a diff: it's easy to read a diff and see what
> changed in the old versus the new version of something.  I can tell if it's
> an improvement without having to digest the entire content.
>
> But the structure of <http://docs.recursivedream.com/twisted/> is a
> sprawling mess of placeholders and half-finished ideas.  It's different from
> the existing documentation in lots of ways; it has a completely different
> stylesheet (which I assume is some standard Sphinx thing we will get rid of
> with the consistent theming work in Kevin's sphinx transition).  I don't
> know what I'm looking at or how to appreciate it.
>
> This is why I started off by complaining about the separate git repository.
>  If you're going to work in a separate repository and a separate format and
> not produce di

Re: [Twisted-Python] Change to ticket workflow

2011-02-06 Thread Tom Davis 
On Sun, Feb 6, 2011 at 5:12 PM,  wrote:

> Hi all,
>
> Last weekend I changed the default owner for all components in the issue
> tracker to be nobody.  I also installed the "DefaultCC" plugin which
> lets us configure a list of users to be added to the cc list of tickets
> on a per-component basis.
>
> The motivation for this change is basically the fact that when people
> see a ticket with an owner, they think that owner is either working on
> the ticket or will be upset if someone else starts working on it.  This
> has really never been the case with Twisted's development process.
>
> Beyond this change, I think it may also be a good idea to remove owners
> from most old tickets as well.  This will probably happen sometime in
> the coming week, so don't be surprised when you look at your ticket list
> and find it empty.
>
>
I've been meaning to recommend this, actually. I think "ownership" conveys
something important—or it should. My actual recommendation was going to be
to mass-remove ownership from tickets that haven't been updated by their
owners "recently" and then to institute some kind of reminder email that
gets sent out with a list of tickets you own that haven't been updated in
the past X weeks. This would at least nudge people to close a ticket or
remove their ownership so the ticket will be back "on the radar," so to
speak.

I've probably got a ticket or two that could be considered stale already and
I don't even have many to keep track of. It's just easy to forget week to
week what exactly I've made a promise to work on; I imagine it's the case
for others as well. Many tickets haven't been updated in years and something
tells me their owners won't be strolling back any time soon. Many of those
probably aren't relevant anymore, period. Perhaps being on the "nobody" list
would give them sufficient visibility to be properly triaged.

Just a thought!


> After this, if you actually want to work on a ticket, there's no reason
> not to assign it to yourself.  The goal here is just to eliminate
> accidental/careless ownership.
>
> Jean-Paul
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Boston Mini-Sprint: February Edition

2011-02-06 Thread Tom Davis 
On Feb 6, 2011, at 9:05 PM, Tenth  wrote:

> We'll be holding another Boston-area Twisted Mini-Sprint on Sunday, February 
> 13th at my place in Somerville, MA... I've sent out invitations to the 
> attendees from last time, plus a few other people who've expressed interest, 
> but if you weren't invited yet, and want to be, let me know!

I am interested in attending, good sir!

> 
> Thanks,
> 
> - Dave
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] twisted can't find internet module

2011-02-10 Thread Tom Davis 
On Thu, Feb 10, 2011 at 1:14 PM, Glyph Lefkowitz wrote:

> On Feb 10, 2011, at 8:08 AM, Stephen Thorne wrote:
>
> I am also very curious about the nature of the "problem horse", as
>
> google translate suggests the first response is about. :-)
>
>
> I did not use google translate, but I was wondering why horses were
> mentioned in the discussion as well.
>
>
> Since the poster hasn't clarified, I thought I'd share this fascinating
> tidbit:
>
> My wife (who was excited to learn the phrase for "bug report" from this
> message) explains that "horse-top" or "on a horse" is a Chinese idiom
> meaning "fast", so the responder was telling the OP to describe their
> problem better, and if they do so, it will be resolved quickly.
>
> I have to admit I'm a bit disappointed; I thought that maybe Problem Horse
> would be Twisted's answer to the Django Pony, but alas we will never get to
> meet it.
>

I must admit that despite the ban on laughing out loud in #twisted, I have
done so in my apartment multiple times over "Problem Horse". I hope its fate
is not yet sealed!


>
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] PyCon 2011 Twisted Sprint

2011-03-02 Thread Tom Davis 
On Wed, Mar 2, 2011 at 11:45 PM, Glyph Lefkowitz wrote:

>
> On Mar 2, 2011, at 11:28 PM, exar...@twistedmatrix.com wrote:
>
> > On 8 Feb, 04:24 pm, exar...@twistedmatrix.com wrote:
> >> Hello all,
> >>
> >> Once again, we will be sprinting at PyCon.  I've just added Twisted to
> >> .  If you plan to attend
> >> (for any amount of time), please add your name to the attendees list.
> >> Also feel free to suggest additional sprint topics.  We won't really
> >> limit sprint topics to things planned in advance, but adding particular
> >> things to the list is a probably a good way to attract more sprinters
> >> and let people do any background research that might be necessary
> >> before
> >> the sprint actually starts.
> >
> > Just a reminder about this.  Please sign up if you plan to come!
>
> All levels of experience are welcome, so if you've never been to a sprint
> before, we'd love to see you.
>
> Sign up as soon as you can though.  Sometimes space is allocated based on
> these lists.  I'm not sure how it's going to work this year, but it's best
> if we know approximately how many people will be there so we can be sure to
> get a big enough room for everyone.
>

Finally signed up; last time the "You must login to edit" message was
hardcoded *and* there was no link to the edit page. That was a confusing
journey.


>
> -glyph
>
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] PyCon 2011 Twisted Sprint

2011-03-03 Thread Tom Davis 
On Thu, Mar 3, 2011 at 1:18 AM, Glyph Lefkowitz wrote:

>
> On Mar 3, 2011, at 12:21 AM, Tom Davis wrote:
>
> On Wed, Mar 2, 2011 at 11:45 PM, Glyph Lefkowitz 
> wrote:
>
>>
>> On Mar 2, 2011, at 11:28 PM, exar...@twistedmatrix.com wrote:
>>
>> > On 8 Feb, 04:24 pm, exar...@twistedmatrix.com wrote:
>> >> Hello all,
>> >>
>> >> Once again, we will be sprinting at PyCon.  I've just added Twisted to
>> >> <http://us.pycon.org/2011/sprints/projects/>.  If you plan to attend
>> >> (for any amount of time), please add your name to the attendees list.
>> >> Also feel free to suggest additional sprint topics.  We won't really
>> >> limit sprint topics to things planned in advance, but adding particular
>> >> things to the list is a probably a good way to attract more sprinters
>> >> and let people do any background research that might be necessary
>> >> before
>> >> the sprint actually starts.
>> >
>> > Just a reminder about this.  Please sign up if you plan to come!
>>
>> All levels of experience are welcome, so if you've never been to a sprint
>> before, we'd love to see you.
>>
>> Sign up as soon as you can though.  Sometimes space is allocated based on
>> these lists.  I'm not sure how it's going to work this year, but it's best
>> if we know approximately how many people will be there so we can be sure to
>> get a big enough room for everyone.
>>
>
> Finally signed up; last time the "You must login to edit" message was
> hardcoded *and* there was no link to the edit page. That was a confusing
> journey.
>
>
> Woah, awesome!  So you're going to be in Atlanta after all?  (Or am I
> mixing you up with someone else whose plans were uncertain?)
>
>
That was me, I'm just bad with status updates. Really excited for my first
PyCon and some concentrated Twisted hacking!
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Announcing Twisted 11.0.0pre1!

2011-03-22 Thread Tom Davis 
On Tue, Mar 22, 2011 at 8:17 PM, Jessica McKellar <
jessica.mckel...@gmail.com> wrote:

> Intrepid Twisted developers and users: from Cambridge, Massachusetts I
> am pleased to announce the arrival of Twisted 11.0.0 pre-release 1.
>
> Tarballs for the pre-release are available at:
>  http://twistedmatrix.com/~jesstess/11.0.0pre1/
>
> Highlights include:
>
>  * a new templating system in Twisted Web, "twisted.web.template",
> derived from Divmod Nevow.
>
>  * improved behavior of subprocess spawning on FreeBSD.
>
>  * an API for constructing endpoints from descriptive strings.
>
>  * twisted.plugin no longer emits a confusing traceback when it can't
> write a cache file.
>
> For more information, see the NEWS file.
>
> Download the tarballs and test away!
>

Awesome! Thanks for doing the release, Jessica! :)


>
> Thanks,
> Jessica
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] prerelease preview predocumentation

2011-03-28 Thread Tom Davis 
On Sun, Mar 27, 2011 at 9:57 PM, Glyph Lefkowitz wrote:

>
> On Mar 23, 2011, at 9:34 PM, Glyph Lefkowitz wrote:
>
> 
>
>
> Anyone have comments about this?  With all the recent excitement about the
> docs, I thought there would be a much more active thread here!
>
> Thoughts about whether we should link it from the front page?
>
>
I meant to get to this sooner, but my weekend was unexpectedly busy. The
docs look awesome! Aside from the common formatting error of mandatory space
after marked up text, I didn't run into anything really odd. One issue on
the index is that both "Twisted Conch" and "Twisted Core" have subsections
called "Twisted Documentation."

It's great to have everything indexed on one page with easy drill-down into
specific sections. It becomes really obvious where the hierarchy can be
optimized and how we can logically go about breaking up the various
sections.

In reply to your original post, I'm still planning to finish the trial
tutorial. I feel like an ass for not doing it this weekend, but I turned out
to be rather occupied. I'm going to make time for it early this week if it
kills me.

-glyph
>
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Information on new endpoints API?

2011-06-13 Thread Tom Davis 
On Jun 13, 2011, at 8:26 AM, exar...@twistedmatrix.com wrote:

> On 12 Jun, 01:34 pm, ores...@orestis.gr wrote:
>>> This is really why we introduced endpoints - to make it possible for
>>> applications to listen on (or connect to) an address that is specified
>>> elsewhere.  Previously, the "easy thing to do" was to only support
>>> TCP/IPv4.  With endpoints, the "easy thing to do" is to work with any
>>> address family/transport type that there is now (or will be in the
>>> future!) an endpoint for.
>> 
>> That's a perfect explanation, many thanks!
>>>> I will be giving a training on Twisted in a few days during the
>>>> EuroPython conference (actually, more of an assisted tutorial than a
>>>> training) and I'm not sure how I should present this. Any information
>>>> would be helpful.
>>>> 
>>>> Orestis
>>> 
>>> Hope this helps!  Good luck with the session. :)
>> 
>> Thanks. BTW, I've spent the past week browsing through twisted's 
>> documentation (esp. the API reference). I have a few ideas that I think 
>> would help newcomers find their away around much easier (and be less 
>> scared of twisteD). The ideas are mostly organisational, the material 
>> is there, if one knows what to look for. Should I create new tickets or 
>> mail ideas to this list?
> 
> It would probably be best if you could get Kevin Horn and/or Tom Davis' 
> attention.  They've both been thinking about making the documentation 
> more accessible lately.  It would be great to incorporate your ideas 
> into the overall plan.

My ears, they burn! But, yeah, in terms of discoverability, the ever-near 
lore-to-Sphinx conversion does a ton for discoverability and makes obvious a 
number of opportunities for organizational improvement (a link to a recentish 
build eludes me, but when you seem them you'll know what I mean). Beyond the 
low-hanging fruit, there are many notes regarding individual docs improvements. 
Feel free to share your own, though I recommend checking Trac first because 
many documents do indeed have tickets. If you need help there let me know.

Speaking of the lore-to-Sphinx conversion, I am contractually obligated to 
inform you that improvements to current documentation is not blocked by the 
pending conversion. And that you have the right to a lawyer.

Cheers,

Tom

> Jean-Paul
> 
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] SURVEY: Have you submitted a patch to Twisted and it never got in?

2011-07-01 Thread Tom Davis 
On Jul 1, 2011, at 1:41 PM, Glyph Lefkowitz  wrote:

> 
> On Jul 1, 2011, at 1:08 PM, chris wrote:
> 
>> doing continuous development based on tools like 
>> svn and trac is really painful and it's really difficult to motivate 
>> yourself to work on a once rejected ticket
> 
> Can you be more specific, please?  What's painful?

I always found it especially irritating to come back to a patch later. If I 
don't already have a patched checkout of Twisted, I need to figure out what 
revision I was at before (or to actually be safe, make a HEAD checkout), then 
reapply my patch, hoping it is still valid.  

With a fork I can check it out any time, rebase to the current master (or 
branch I'm working on), having my changes reapplied for me. When I have made 
more changes I just push it up. No changes to tickets or switching keywords or 
watching Trac reject my patch file 10 times then clearing all my cookies or 
whatever.

I've always admired Twisted's standards and process; I think they have made it 
possible for such a huge project to maintain working order for so long. The 
tools could use an upgrade, though.

> 
> Procedurally, it's almost the same number of clicks (except for the 
> unfortunate need to type the word 'review') to do this on Github or 
> Launchpad.  What part of the process is painful?  If you're not a committer, 
> we're not going to let you run code on our buildbots either way without a 
> cursory review (that's just a recipe for automated attacks) so it's not like 
> you get past that step for free, either.
> 
> Plus, you can use the DVCS of your choice to actually author the patch.
> 
> 
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Website visual improvements

2011-11-06 Thread Tom Davis 


On Nov 6, 2011, at 12:51 PM, Jonathan Jacobs  
wrote:

> Hello,
> 
> I recently volunteered to make some visual improvements to the Twisted Trac 
> website. I received a lot of good feedback and suggestions from the IRC 
> channel, most of which I took to heart and fine-tuned the changes. I think 
> everyone is generally happy with the changes, I'm happy with the changes and 
> I'd like help with moving things forward to eventually deploy these changes.
> 
> The branch is currently up for review on Launchpad[1], the merge proposal 
> contains links to some[2] static[3] pages demonstrating the style changes. 
> (It is worth noting that there are some quirks that are as a result of "File 
> -> Save As" in Firefox, I wouldn't worry about these.)
> 
> I am willing to help with the final deployment of the site changes as well as 
> integrating the new styling with:
> * the Sphinx documentation and documentation tools;
> * the Lore documentation (which I see thijs recently did some work on) if 
> that is necessary;
> * and the pydoctor API documentation.
> 

Wow Jonathan, these changes look great! 

> -- 
> Jonathan
> 
> 
> [1] 
> 
> [2] 
> [3] 
> 
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] Twisted Project Jobs Volunteer

2011-11-09 Thread Tom Davis 
On 11/09/2011 07:49 AM, Tim Allen wrote:
> On Wed, Nov 09, 2011 at 12:50:23AM -0800, Glyph Lefkowitz wrote:
>> On Nov 8, 2011, at 7:39 PM, Tim Allen wrote:
>>> As far as I know (having written most of the documentation in the linked
>>> wiki page, and from a brief skim through the git-svn manpage) it's
>>> impossible to make a "shallow" clone with git-svn (something like an
>>> ordinary "svn checkout", or "git clone --depth N"), so anyone who wants
>>> to contribute to Twisted via git needs to clone the repository from
>>> scratch (potentially overloading the SVN server, although nobody seemed
>>> to notice or complain when I was doing my git-svn clone), or just copy
>>> a tarball of somebody's comprehensive, elaborate, automatic mirroring
>>> setup.
>>
>> This is the part I don't understand.  Why doesn't 'git clone' work
>> right in the face of svn metadata?
>
> Git has a ".git" directory in each repository, and expects certain files
> to be present within it. If there's more stuff that it doesn't know
> about, it just ignores it. git-svn keeps its metadata in other files
> that git-clone doesn't know or care about, and hence they don't get
> cloned.
>
> I guess there's an argument for not cloning them - just because person
> X has particular access rights to an SVN server doesn't mean that person
> Y should have them just because they cloned a repository from X.
>
>> bzr-svn has some metadata it caches about the svn repository which
>> doesn't stick around in the bzr repo or branch, but (from the
>> performance of using it, at least) it doesn't need to stop the world
>> and grab all of that data for most operations.
>
> In a git-svn-cloned repository, ordinary git operations are as speedy as
> you'd expect. "git svn fetch" is slow because (I think) it has to
> separately request each changed file from each SVN revision, and I think
> there's some other operations that are slow because they involve talking
> to the SVN server (like 'tell me what SVN properties are attached to
> this file').
>
>> It would be better (for most users) to point to a canonical way to get
>> access to a git-svn clone than to document how to make one, if making
>> one takes 24 hours :).
>
> Don't worry, it doesn't take 24 hours! It's *much* longer than that! ;)
>
> (as the wiki page states, in early 2010 and from the other side of the
> world it took about a week; I don't have a feel for how it changes over
> time)

It's worth noting that you aren't *required* to clone all eight trillion 
Twisted revisions in order to get a working clone. Doing `git svn clone 
-rN:HEAD ` where `N` is some revision number will only clone from 
that revision. Obviously you will not have the entire history of the 
repository at this point, but I highly doubt that would be a meaningful 
loss for the majority of use cases.

I mean, yeah, it'd be nice to have a full git clone, but if you just 
prefer to use git for development and want to submit patches to Twisted 
it's hardly an insurmountable task compared to the other requirements 
for successfully working a ticket to completion.

>
>>> I'm not sure why that would be, except that possibly they found
>>> a tarball of somebody else's git-svn clone and forgot to update it, or
>>> they're confused about the best way to get cloned from some unofficial,
>>> no-longer updated mirror. Fixing this probably depends on having the
>>> canonical, correct, convenient instructions and advertising them widely.
>>
>> You edited GitMirror before, you can do it again :).
>
> I'm editing it to include what we've discussed here, as well as a few
> other things that I researched this afternoon and put into a reply that
> my MUA ate before it was sent.
>
> I believe the next step should be that somebody with the required
> permissions should connect to a machine on the same physical network as
> the SVN server and run:
>
>  time git svn clone --stdlayout --prefix="svn/" \
>   svn+ssh://svn.twistedmatrix.com/svn/Twisted
>
> ...then check the load on the SVN server and see if it's going to be an
> issue to let the clone complete. If the clone completes successfully,
> then (a) we know about how long it takes, and (b) we have a "seed"
> repository we can potentially put up for people to download. I'd be
> happy to download it, check it, and write up some documentation about
> how people should update it. If it doesn't complete successfully, we
> should have some helpful error messages, adjust the clone command line
> and try again.
>
> ___
> Twisted-Python mailing list
> Twisted-Python@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python