Re: [Twisted-Python] Refactoring Documentation
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. This doesn't conflict with the reuse I've been supportive of (and for good reason: there's a lot of decent documentation already there) but it does conflict with the Twisted development policies. At the end of the day, I can't really submit patches to existing documentation until said doc
[Twisted-Python] Fingering Finger
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] Refactoring Documentation
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. > 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 :). > 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. > 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! As you have discovered here, drawing attention to a ticket in this "stuck" state will often cause it to get un-stuck. So please keep doing that. > 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 th
[Twisted-Python] Weekly Bug Summary
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 Tickets Open 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 instead of \r\n (opened by jasonjwwilliams, closed by exarkun, duplicate) defect webhttp://twistedmatrix.com/trac/ticket/4814 [#4816] twistd --uid without --gid breaks (opened by thobbs, closed by exarkun, duplicate) defect core http://twistedmatrix.com/trac/ticket/4816 = Low = [#3372] deprecate --extra option to trial (opened by exarkun, closed by cyli, fixed) tasktrial
Re: [Twisted-Python] Weekly Bug Summary
> > 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] Weekly Bug Summary
On Jan 23, 2011, at 12:36 AM, Tom Davis wrote: > 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! Dude, you totally buried the lead. > 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 This is the real story. Great work everybody! -11 is a pretty significant week! (Now let's please do that continuously for 3 years...) ___ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Re: [Twisted-Python] Refactoring Documentation
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/forgotten corners become documented in a way that makes it easier. And just point out when the current status of something is way too ambiguous to be actionable for more than a couple folks who are too busy to deal with it. > > 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 month
