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