=== Ursinha is now known as Ursinha-afk === mrevell is now known as mrevell-lunch === mrevell-lunch is now known as mrevell [15:00] #startmeeting [15:00] Meeting started at 09:00. The chair is bac. [15:00] Commands Available: [TOPIC], [IDEA], [ACTION], [AGREED], [LINK], [VOTE] [15:00] hello and welcome to the mostly-weekly reviewers meeting [15:00] who is here today? [15:01] me [15:01] me [15:01] danilos, bigjools, gary_poster, gmb: ping [15:02] me and pinging... [15:02] EdwinGrubbs, noodles775, jelmer, mars: ping [15:02] me [15:02] me [15:03] danilos: can you round up your team? [15:03] bac, only henning is around but seems to not have come back from lunch [15:04] BjornT: are you interested in attending? if so i'll continue to ping you. let me know. [15:04] me [15:04] for me team, I pinged leonardr and mars, and salgado is out [15:04] s/me/my/ [15:05] me [15:05] allenap: ping === Ursinha-afk is now known as Ursinha [15:05] [topic] agenda [15:05] me [15:05] New Topic: agenda [15:05] me [15:05] * Roll call [15:05] * Agenda [15:05] * Outstanding actions [15:05] * Mentoring update [15:05] * New topics [15:05] * Multiline parameter lists in function definitions vs. function calls [hennnige, jtv] [15:05] * Reduction of negation preferred over "common case first" in if statements? [henninge, jtv] [15:05] * Should doctests only be testable documentation? [abentley] [15:05] * Peanut gallery [15:05] [topic] outstanding actions [15:05] New Topic: outstanding actions [15:06] [topic] * bac to restart discussion on community reviewer/committers after feedback from elmo [15:06] New Topic: * bac to restart discussion on community reviewer/committers after feedback from elmo [15:06] i (just barely) did this item by sending an email to the internal list this morning. i hope we can have a good discussion there and come to a concensus. [15:07] [topic] mentoring update [15:07] New Topic: mentoring update [15:07] For those of us playing at home, what was the 'feedback from elmo'? [15:07] hi wgrant [15:07] Regarding the mentoring update, jelmer is doing well - holidays this week though :) [15:08] wgrant: elmo shared the opinion of others that since launchpad is a service with the obligation to protect our user's private data we cannot allow community code contributions to go into the tree that automatically rolls to edge without a Canonical-employee review [15:09] bac: OK. Thanks. [15:09] wgrant: i'd like to get your feelings on the matter off-line whenever you have time. [15:10] noodles775: thanks for the update [15:10] [topic] * Should doctests only be testable documentation? [abentley] [15:10] New Topic: * Should doctests only be testable documentation? [abentley] [15:10] * bac going out of order since henninge is not here [15:10] * noodles775 sits back a bit. [15:11] I had gotten the impression that we had a consensus that doctests should be testable documentation, and everything else should be unit tests. [15:11] there seems to be some confusion on what testable documentation really is [15:12] bigjools, could you expand? [15:12] does testable documentation live in 'doc' directories or is anything that uses the doctest framework? [15:12] I was hoping you would :) [15:13] abentley: depending on who I speak to they all have a different idea of what constitutes documentation, so I think we need to carefully define what we want to document [15:13] I'd say "minimal test that demonstrates how API is used" would be classified as documentation [15:13] Perhaps definitions are part of the problem. [15:13] "minimal"? [15:13] heh, they most certainly are [15:13] yes, minimal, at least imho [15:13] My definition would be a work whose contents were primarily descriptive, but contained examples of how to do things. [15:14] perhaps it would be better to specify an audience? [15:14] or... [15:14] minimal in the sense that real doc tests should test all corner cases [15:14] s/better/helpful/ [15:14] Basically, something I might see in a reference book. [15:14] maybe we have use cases for different types of doc tests [15:14] er s/should/should NOT/ [15:14] +1 for abentley's def. [15:14] bac, danilos, ack [15:15] so yes +1 for abentley's as one type, but also it's sometimes useful to see test cases written in a narrative style [15:15] A counterexample would be a work that contained mainly tests, and showed numerouse ways that the API would fail. [15:15] agree with bigjools, but worried about how to delineate [15:16] there are also corner cases which are tested with a single line of code but need a lot of narrative [15:16] fine with abentley's general approach [15:16] bigjools, many things are useful that are not, on balance, worthwhile. [15:16] abentley, I prefer your definition. In the view examples you cited, I think base and mixins need documentation since we expect engineers to reuse the view. but most views that get their forms exercised are better tested in unittest [15:16] AIUI, doctests are much slower than unit tests. [15:17] I find they are also fragile. [15:17] actually they can be much quicker [15:17] since the db is not reset between tests [15:18] again, it's a matter of drawing the lines, and I am positive we can't do it here (anybody remembers actual pagetest stories, or series of stories?) [15:18] abentley, doctests are faster because they reuse data instead of setting up for each test. [15:18] abentley, conversely, adding to a doctest can be painful [15:19] Anyhow, our definition of "testable documentation" doesn't matter unless we agree that our doctests should be testable documentation. [15:19] and agreeing doesn't matter unless we all consider it a same (or well, similar enough) thing ;) [15:19] I've looked at the test style guide and it definitely doesn't recommend one style over another. [15:20] But I need to know whether I should be watching for doctests that aren't documentation in my reviews. [15:20] I consider an ideal doctest as one that describes to me how I should drive the object it's documenting [15:21] me ;) [15:21] bigjools, I agree [15:21] anything else distracts [15:21] I think you should, but there're also many old tests [15:21] bigjools, that sounds somewhat compatible with what I was saying. [15:21] for any new one: request it; for old ones, suggest it [15:22] maybe we need a second doctest dir "unit-doc" and move the old crappy tests into it [15:22] then we have a target to clean up [15:22] I figure most of them are soyuz :) [15:22] bigjools, +1 (on everything except the name) [15:22] bigjools, abentley I think the distinction is that the documentation may not be in doc/ if is for a non intrerface [15:22] bigjools, but a component of "testable documentation" would be prevalence of text, rather than just tests interspersed with a few words. [15:23] sinzui: +1, that's what I was suggesting a few minutes ago [15:23] abentley: we could keep that style, just not put it in "doc" [15:23] sinzui, when you say Interface, do you mean the zope construct? [15:24] abentley, the tests in doc/ should be about what is defined in interfaces/ [15:25] totally [15:25] sinzui, it seems to me that there are items which are not defined there which are useful. [15:25] For example, the job runner. [15:25] doc/tales.txt for example [15:25] Or the direct branch committer. [15:26] it's obvious to me that we need more than one "doc" directory [15:26] I think "documenting interfaces" is a subset of abentley's "reference documentation for developers" [15:26] When I document a view mixin, I expect it to be in browser/tests or browser/doc [15:27] It would seem silly to document IRunnableJob and not the ways of using it, for example. [15:27] * sinzui never understood why lp//tests is where all unittests go except for browser/tests [15:28] sinzui, actually, ours usually go in lp/code/model/tests [15:28] abentley, I know, and that violates the flacoste rules for the apocalypse [15:29] * sinzui had actually written migrater rules to put tests below the implementation class [15:30] can we drive to a solution here, or do we need to take this to the list? [15:30] Okay, so how do we move this discussion forward? [15:30] I am thinking list [15:30] we talk about this 3 times a year [15:30] lol [15:31] because we never agree on anything :) [15:31] I don't think we're going to come to a decision here. [15:31] there will be no consensus, We need a dictator [15:31] I say *somebody* go and define it; BjornT claimed to be interested in the past [15:31] * bigjools steps up [15:31] So it is take it to the list again [15:31] * sinzui wants a doctest-> unittest converter though [15:31] +1k [15:31] bigjools: dictate! :) [15:31] danilos: clean my shoes [15:31] sinzui, we've got one, it's called "sinzui" [15:32] bac: why the list, why not ask that we read all the previous threads [15:32] lmao [15:32] bigjools, anyone, you heard the dictator :) [15:32] sinzui: hmmm, good point [15:33] no lists, no discussions, somebody who cares enough go ahead and define the policy, put it in the wiki and we'll start pointing people at it in our reviews [15:33] sigh [15:33] what, did I say something? don't mind me. :-) [15:33] I think this discussion has been productive. abentley and bigjools provided good definition of documentation and I think all of us can find doctests that fail that definition [15:34] this is important enough to gather more opinions please [15:34] sinzui: +1 [15:34] we'll get opinion as we build the policy [15:34] s/opinion/opinions/ [15:34] does else anyone want to create a second doctest dir to shove all the non-interface documentation into? [15:35] we can even create a standard topic in this meeting to discuss what has come up during reviews last week [15:35] We are an open source project now, we do not need democracy, we want leadership via meritocracy. [15:35] or the other way, make a new one to put the interface docs in [15:35] Is there anyone against the idea of requiring that new doctests are testable documnetation? [15:35] bigjools, I don't mind [15:35] sinzui, +1 [15:35] abentley, +1 [15:36] yes, provided there's a written definition of what that is [15:36] but you said it earlier so c&p is fine [15:36] abentley: +1, and even a strong push that when updating current doctests, converting them. [15:36] fine with me [15:36] ok, so it *does* sound like we're coming to an agreement [15:37] s/current doctests/current doctests that are not documentation [15:37] I will take the item of collecting the thoughts and making a first draft of the new policy on the wiki, for us to refine later. [15:37] (I'd say we've always had a majority agreement on high-level points, we just never implemented that agreement into policy) [15:37] bac, thanks a lot! [15:37] bac, thank you. [15:37] [action] bac to define new doctest policy. [15:37] ACTION received: bac to define new doctest policy. [15:38] and we can have more focused discussions on the finer points here in the coming weeks [15:38] thank you abentley for pushing the discussion forward [15:38] bac will take off his mask as reveal that he is the supreme leader [15:38] bac, np. [15:38] heh [15:38] [topic] * Multiline parameter lists in function definitions vs. function calls [hennnige, jtv] [15:38] New Topic: * Multiline parameter lists in function definitions vs. function calls [hennnige, jtv] [15:39] Ah yes. [15:39] note we have six minutes, so let's not dawdle... [15:39] I have since been told that this has been discussed recently, so now I am just asking what I should put in the style guide. [15:39] http://paste.ubuntu.com/414360/ [15:39] LINK received: http://paste.ubuntu.com/414360/ [15:40] henninge, afaik, we've allowed both styles so far [15:40] There seems to be different ways to format multi line definitions to multi-line calls, is that correct? [15:40] henninge, or well, perhaps not for function definitions [15:40] most multi-line fcn calls don't follow the style shown [15:40] danilos, for function calls, I have not been allowed to use the first style. [15:40] or was I told rubbish? [15:41] henninge, you can use the first style for calls as well; second style is not customary in function defs [15:42] danilos: style guide only allows the second style for calls. [15:42] abentley: that's what the paste shows, that the styleguide *currently* says the second for calls... and not the first. [15:42] noodles775: yes, I was told, though, that somewhere it was agreed to use the first for definitions. [15:42] noodles775, right. danilos seemed to be suggesting using the first style for function calls was permissible. [15:43] I am just asking if that is the case and I'll update the style guide. [15:43] Yep, so if so, let's update the styleguide :) [15:43] * danilos thought it was, and I've written numerous lines of code in that style and nobody complained [15:43] danilos: get jtv as a reviewer ... [15:43] ;-) [15:43] danilos: me too. i prefer the first. [15:44] bac: for calls or definitions? [15:44] Using the first style for function calls does have the advantage that it's suggested in PEP-8 [15:44] we could simple allow both styles for both situations [15:44] henninge: calls. the first only for defn [15:44] henninge, I prefer them for both, I resort to second style for calls only when function name is already long and I'd need 5 lines for 5 parametes [15:45] bac, +1 [15:45] bac, danilos +1 [15:45] I'll put that in the style guide. [15:45] if your function call params are spreading that far, I'd be tempted to make a container object, FWIW [15:45] do we need a vote? [15:45] i think not. [15:45] bigjools, sometimes just the function name is long [15:45] danilos: shrtn it :) [15:45] [action] henninge to update the style guide [15:45] ACTION received: henninge to update the style guide [15:45] bigjools, we can start considering names like 'zap_it' :) [15:45] btw, style guide is this to me: https://dev.launchpad.net/PythonStyleGuide [15:46] henninge: may we roll your other item to next week? [15:46] bac: that's fine. [15:46] great. [15:46] this has been a very productive meeting. [15:46] thanks for coming and participating. [15:46] #endmeeting [15:46] Meeting finished at 09:46. [15:47] thanks bac [15:47] bac, thanks. [15:47] bac, all, thanks [15:48] thank you === danilos is now known as daniloff === gary_poster is now known as gary-lunch === gary-lunch is now known as gary_poster === EdwinGrubbs is now known as Edwin-lunch === Edwin-lunch is now known as EdwinGrubbs