[Twisted-Python] Let's talk about maintaining Lore (and validity of tickets)

[Glyph]

Jean-Paul recently closed a Lore ticket as invalid, and suggested we have a discussion about Lore's future direction.  This strikes me as a very good idea, and so I wrote a message which is a bit too long (for which I apologize) to kick that off.

The discussion began here: <http://twistedmatrix.com/trac/ticket/6313#comment:7>.  In said suggestion, JP said:

> I am rejecting this Lore feature as unnecessary for Twisted's current documentation needs.

With regard to this specific point: the bug was discovered when building the documentation for the systemd-howto-5601 branch: <https://buildbot.twistedmatrix.com/builders/documentation/builds/2919/>.  Presumably a better error would have facilitated development.  So, while better error reporting of this error case may not be "necessary" I think it clearly would have been beneficial in this case and would perhaps be beneficial in similar cases in the future.  Is necessity or benefit the standard which keeps a ticket open in our tracker?  Do we have a documented standard for how necessary (or beneficial) a ticket must be anywhere?

> However if there is genuine interest in enhancing Lore (specifically: obsoleting the lore2sphinx conversion tool), then I'm open to reconsidering that.


I don't think these two paths (lore2sphinx and continuing to maintain lore) are necessarily mutually exclusive.  Also I think it implies something about the current state of affairs that isn't accurate - e.g. that the Twisted team has agreed that Sphinx will surely replace Lore and that we are making progress on that process of placement more than we are maintaining Lore itself.

Unfortunately, I think it will be clear to anyone following its progress that lore2sphinx is unmaintained and the sphinx migration effort is stalled.  Nobody has committed to <https://bitbucket.org/khorn/lore2sphinx> in a year and a half, about the same amount of time that <http://twistedmatrix.com/trac/browser/branches/sphinx-conversion-4500> has been idle as well.  By contrast, <http://twistedmatrix.com/trac/browser/trunk/twisted/lore> has seen commits - albeit not many - within only a couple of weeks.  So, empirically, we're already maintaining lore and lore2sphinx is currently "obsolete"; really the question should be if we want to reverse that path.

I also have no objection if someone wants to complete the lore2sphinx work, but if the lore2sphinx buildbot were to die tomorrow and go offline, I wouldn't be particularly anxious to spend a lot of resources to fix it.

My position on this was always that if someone wanted to improve the documentation, they were welcome to do so, and if they wanted to use Sphinx to do it, that's great too.  I just wasn't willing to tolerate any period where our toolchain was broken and we couldn't generate documentation for a release.  And a good thing we didn't, by the way!  If we had said "go ahead, pull the trigger, whatever, it's OK to break trunk for a little while!" we wouldn't have had any documentation toolchain for the last 2 years.

(I hope that everyone takes this to heart the next time someone wants to break our development process "for a little while, just during the migration" to move to Github, or Jenkins, or Travis-CI or whatever.)

> Basically, this ticket is a demonstration of "stumble around in the dark" development in action. We don't need more of that (and I know I'm as guilty as anyone else). If someone wants to turn on a light, great. Otherwise, everyone out of the basement and find something more valuable on which to spend your time.

I don't think that this metaphor is particularly... illuminating.  While I can sort of guess what you're talking about, it's all pretty implicit and seems to make several assumptions I am not sure that I agree with.

What's wrong with stumbling around in the dark?  If we had a hierarchically-managed product-driven organization, then having focus and a clearly communicated, consistently enforced shared goal would be important to effectively produce that product, but community projects don't seem to work that way.  Consensus is important, but even given a consensus, pool of resources for development that we can allocate via executive decision is fairly small, and is just about sufficient to pay for code reviews of the contributions that we receive and to take care of administrivia, not to do substantial new development.  We have to rely on volunteer contributions for that.

I'm also sure our tools have a million boring little niggling bugs that need to be discovered and addressed so that the average experience of using and working on Twisted is as pleasant as possible, and we don't want to discourage people from reporting them; that's also a useful volunteer function.

Does it harm any members of the Twisted development team to have other members of said team (by the way hi rwall congrats on your commit access) to file these sorts of legitimate, but trivial bugs in uninteresting bits of support code in Twisted, like lore or our release-management tools?

To play my own debate opponent here: perhaps it does.  The bug tracker is a resource, new bugs consume attention of core developers as we each probably pay attention to see if users are reporting serious problems we should fix.  Collectively, that attention is arguably our most precious resource and we should be careful not to waste it.  So we don't want the shared resource of the issue tracker to suffer from a tragedy of the commons and get filled up with junk bugs so we can't find the good ones.  Closing tickets as invalid to draw a line around what we're trying to get accomplished and to prevent future attention from being wasted.

But, attention is worthless without enthusiasm and skill, and having one's tickets closed as invalid does potentially sap one's enthusiasm and thereby one's motivation to acquire further skills.  So more determinedly closing things as invalid may be robbing Peter to pay Paul.

Also, in this case, I would question the classification of "invalid"; I like to use the "invalid" on bugs which are clearly not actionable.  #6313 describes a clear problem (a traceback), and after clarification, a clear course of action (improve the error message).  If we don't believe the problem should be fixed, then we should say "wontfix".  I think this distinction is important because actually invalid (too vague as to be actionable in any way) bugs are in fact a waste of time, and provoke a good deal of pointless discussion before they die.  Wontfix bugs are more of a good-faith mistake on the part of the reporter :-).

With tickets such as this one, I think that what we (members of the Inner Circle, I guess, we should have secret handshake or something) ought to be doing is:

setting the priority to 'lowest' (while this has very little real practical or process-enforced consequence, it should at least help others not get distracted by it in the future if they're looking for something to do)
directing the bug reporter to a more useful ticket by linking to something that we wish someone would work on
Once there's a positive pointer towards something more useful, explaining that (maintaining lore/changing the background color of the website/changing the order that we send response headers in HTTP) is peripheral to Twisted's mission of providing awesome internet APIs to programmers everywhere, but that we'd still be happy to receive a patch that addressed the issue with our code, provided that it adheres with all the relevant testing, coding standard, and compatibility requirements and doesn't waste a reviewer's time

It's challenging to put useful comments on tickets, especially apparently pointless or ill-defined tickets.  It's also just tiring: a lot of the comments one needs to make are incredibly repetitive and redundant.  But, since I believe it's clear that few, if any people actually get their priorities of what to do for Twisted by scanning the bugtracker for recently-filed open issues, I posit that there's not a lot of value in ticket triage that doesn't make its primary goal the repeated communication of documented project policy, existing consensus, and constant positive suggestions as to what contributors should take as a next step.

In this particular case, that means that "everybody out of the basement" is a vague, confusing, and unhelpful comment that just makes feels mildly insulting to the other people participating in the discussion on the bug.  "I would prefer it if you would work on a high-priority ticket like ticket 84 instead of this one, since I believe the Twisted team has a general consensus that lore will be obsoleted and no-one wants to be responsible for it; see ticket 4500 for more details on one effort to do that.".

More generally, I think that when one of us is tempted to shut down a bug like this, a better thing to do would be to write a wiki page or a blog post that can be refined by discussion, and can be an artifact that can be the point of reference for some rough consensus (like, e.g. <http://twistedmatrix.com/trac/wiki/CompatibilityPolicy>) updated by subsequent discussions, and then link to that discussion.

This does all sort of raise the question of "why do we bother to keep a database of tickets around, anyway", and how we should address the warehousing of a potentially increasing number of hypothetically valid bugs that we just don't care enough about to fix.  I haven't really addressed those questions very well here, so I do hope to hear more from all of you about that issue.

So, rwall, hopefully now you'll go close #84 instead of either updating 6313 or responding to this message :).

-glyph

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20130301/a43b93ca/attachment.htm