I've been quietly lurking on this thread as a n00b to the Drill community :). I like the approach that's been proposed, and agree that setting an example for others to follow will be a great motivating factor for others to follow suit. On the MapR end, I'll work with the team to "encourage" more design docs.
-- Zelaine On Tue, Oct 20, 2015 at 2:49 PM, Parth Chandra <par...@apache.org> wrote: > I think that's a reasonable approach. Personally, I don't think a mandated > policy works everywhere and generally slows things down in a fast moving > project, so this is probably the best way forward. > > Perhaps we can begin with some of the pending items that Jacques brought up > earlier. :) > > Parth > > > > On Tue, Oct 20, 2015 at 2:39 PM, Jacques Nadeau <jacq...@dremio.com> > wrote: > > > I hope everybody agrees that we need more design documents and more > design > > document review. Given that contributions are on a voluntary basis, it is > > my perspective that we change the current behavior by modeling and > > rewarding the preferred behavior (as opposed to establishing top-down > > mandates). To me, that means two things: > > > > - Start posting more & better design documents (model the behavior) > > - Start providing more/better feedback on what other people propose > and > > share (reward that behavior) > > > > I'll work with the contributors I know to make progress on each of > these. I > > would hope that others would also try to shape this behavior with > > contributors they know. > > > > When a number of the members of the community start modeling both of > these > > behaviors, I would support establishing a formal policy around mandating > > these behaviors. > > > > > > -- > > Jacques Nadeau > > CTO and Co-Founder, Dremio > > > > On Tue, Oct 20, 2015 at 10:22 AM, Jason Altekruse < > > altekruseja...@gmail.com> > > wrote: > > > > > Ted, > > > > > > One small point I would make on the relationship between the design > docs > > > and the current markdown based user level docs. I think that these > > designs > > > belong in both the source as well as the website. Currently due to how > > > github has the "pages" feature set up, we have the markdown in the docs > > > stored in a branch with a completely separate root from the regular > > source. > > > > > > I don't see it as a major issue, I just think we should pick one of the > > > sources as the location that PRs are expected to be opened against and > > copy > > > them over to the other tree after the review is complete and it has > been > > > checked in. > > > > > > Overall I think it makes a lot of sense to put comments on a design doc > > in > > > a pull request. The only downside I see is managing diagrams and > things, > > > which would be easier to handle in google docs. I think allowing > binaries > > > in the repo (which can be linked from the markdown) for these resources > > > could serve the purpose of exposing them and managing different > versions > > of > > > the diagrams throughout a review period. > > > > > > On Mon, Oct 19, 2015 at 11:31 PM, Aman Sinha <asi...@maprtech.com> > > wrote: > > > > > > > I feel like there are 2 broad issues: > > > > - there should be a targeted group of people for a design review of > a > > > > particular feature or enhancement. The target group should be based > on > > > > expertise in a component. After all, this is what one would do in a > > > > physical in-person design review - we would invite a subset of > > developers > > > > who have the relevant expertise. Just as we assign specific > > > > code-reviewers, we could assign a 'group of design-reviewers'. This > > > will > > > > remove ambiguity about who are the expected set of people to respond. > > I > > > > think if I were to start asking naive questions about a component > > which I > > > > really did not know much about it would not be the most efficient use > > of > > > > everyone's time. > > > > > > > > - it seems to me the lack of response on reviews that are > outstanding > > > > should not necessarily influence the general expectation of writing > the > > > > design for features/mini features. It always seems to help in > flushing > > > out > > > > both the internal and externally visible aspects of the feature. > > Related > > > > to this is the question 'what type of review or response to a review > > > > comment is considered adequate' ? The ideal goal is to get to a > comfort > > > > level of an interactive discussion where one can go back-and-forth > > > > especially on some core topics. However, this is not easily > achievable > > > in > > > > a virtual community and some compromise is often needed to make > > progress. > > > > > > > > Aman > > > > > > > > > > > > > > > > On Mon, Oct 19, 2015 at 11:54 AM, Parth Chandra <par...@apache.org> > > > wrote: > > > > > > > > > Agreed, that we need to have a better response from the dev > community > > > > when > > > > > a proposal is put forward but the absence of a response does not > > imply > > > > that > > > > > we need not write any design down. The document has many consumers > > down > > > > the > > > > > road (new contributors, documentation, and even end users who want > to > > > > > understand the internals). More immediately the design document > will > > > help > > > > > code reviews because the developer's intent is explicitly stated. > > And, > > > > of > > > > > course, without the design document, there can never be any comment > > or > > > > > community participation. So even if only a few people comment, we > are > > > > still > > > > > much better off. > > > > > > > > > > On a more philosophical note, I believe that the ability to write a > > > good > > > > > design document translates directly into the ability to write good > > > code. > > > > If > > > > > you cannot express your design clearly, the design itself is > probably > > > not > > > > > clear, and the implementation will be even less so. (I'm not > > religious > > > > > about this, I mention it only to explain where I'm coming from). > > > > > > > > > > I did propose that we need to have a design discussion limited by > > time. > > > > > Very often, a potential reviewer will put off a comment for later > > when > > > > > (s)he gets more time and then, of course, never gets around to it. > > > Maybe > > > > > having a limit will get some people to respond in a more timely > > > fashion. > > > > > This is the same as having a 'public comment' period; if no one > > > responds, > > > > > then the design, as proposed, stands. > > > > > > > > > > I have a few more observations, especially about using JIRAs. I > > feel a > > > > > shared document is probably the best way to comment on designs - I > > find > > > > > JIRAs are hard to carry out a discussion in and looking for a > > specific > > > > > design some months down the road is a little bit like [1] . > > Secondly, > > > > > there are JIRAs which have a fair amount of detail, especially > about > > > the > > > > > implementation, but implementation details may not be sufficient > as a > > > > > design document. Finally, I sometimes see that the pull/review > > request > > > > > follows immediately after the creation of the JIRA and/or after a > > > > comment. > > > > > This really means there is no actual discussion before > implementation > > > > and I > > > > > think this is best avoided. > > > > > > > > > > These are general comments on what I feel is the right way > forward. I > > > > would > > > > > rather not go into specific instances until we are all in general > > > > > agreement. I would also venture to suggest that any developer > waiting > > > for > > > > > comments should use the hangouts to ask committers and other > members > > to > > > > > comment and drive the review forward. > > > > > > > > > > Are there any other thoughts out there? > > > > > > > > > > Parth > > > > > > > > > > [1] http://www.goodreads.com/quotes/tag/bypass > > > > > > > > > > > > > > > On Sun, Oct 18, 2015 at 4:44 PM, Jacques Nadeau < > jacq...@dremio.com> > > > > > wrote: > > > > > > > > > > > Parth, > > > > > > > > > > > > Thanks for bringing this up. We definitely need to do a better > job > > of > > > > > > discussing development decisions. I think whether this is done > as a > > > set > > > > > of > > > > > > descriptions and comments on JIRA or a formal doc on Google is > less > > > > > > important (and I wouldn't be inclined to enforce one over the > > other). > > > > > > > > > > > > That being said, I think there is something else that limits the > > > > success > > > > > of > > > > > > such an effort. We first must ask: how do we get more people > > > responding > > > > > and > > > > > > providing feedback among the things people have already posted. I > > > know > > > > > I've > > > > > > experienced silence numerous times when asking for feedback and > so > > > have > > > > > > others. Some recent examples I've seen in the community: > > > > > > > > > > > > - DRILL-3738 has received very little to no feedback despite > > > providing > > > > > an > > > > > > initial design document > > > > > > - DRILL-3229 has one general response (ask for more detail) from > > you > > > > > with > > > > > > a follow-up from Steven but no additional feedback on the actual > > > > proposal > > > > > > > > > > > > So I put it back to you and the general list, how do we get > people > > to > > > > > > provide more feedback on all contributions and proposals? I think > > it > > > > goes > > > > > > beyond designs. More issues should be opened with better > > descriptions > > > > and > > > > > > proposals around why one would do something. When the basic > outline > > > has > > > > > > consensus and feedback, people can move to more thorough designs. > > Why > > > > > > haven't we seen response on these issues? > > > > > > > > > > > > I can't see a requirement of reviewed design docs being enforced > > > until > > > > we > > > > > > start to seeing people providing feedback on feature proposals > and > > > > > existing > > > > > > (albeit thin) design documents. So +1 long term but -1 until > people > > > > start > > > > > > to respond and provide feedback on the outstanding items. > > > Contributors > > > > > need > > > > > > to perceive value in presenting a design doc. Let's get the WIIFM > > > right > > > > > so > > > > > > that developer incentives are aligned. > > > > > > > > > > > > Jacques > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > Jacques Nadeau > > > > > > CTO and Co-Founder, Dremio > > > > > > > > > > > > On Fri, Oct 16, 2015 at 10:21 AM, Parth Chandra < > par...@apache.org > > > > > > > > wrote: > > > > > > > > > > > > > Hi guys, > > > > > > > > > > > > > > Now that 1.2 is out I wanted to bring up the exciting topic of > > > design > > > > > > > documents for Drill. As the project gets more contributors, we > > > > > definitely > > > > > > > need to start documenting our designs and also allow for a more > > > > > > substantial > > > > > > > review process. In particular, we need to make sure that there > is > > > > > > > sufficient time for comment as well as a time limit for > comments > > so > > > > > that > > > > > > > developers are not left stranded. It is understood that > > committers > > > > > should > > > > > > > ensure they spend enough time in reviewing designs. > > > > > > > > > > > > > > I can see some substantial improvements in the works (some may > > even > > > > > have > > > > > > > pull requests for initial work) and I think that this is a good > > > time > > > > to > > > > > > > make sure that the design is done and understood by all before > we > > > get > > > > > too > > > > > > > far ahead with the implementation. > > > > > > > > > > > > > > [1] is an example from Spark, though that might be asking for a > > > lot. > > > > > > > > > > > > > > [2] is an example from Drill - Hash Aggregation in Drill - This > > is > > > an > > > > > > ideal > > > > > > > design document. It could be improved even further perhaps by > > > adding > > > > > some > > > > > > > implementation level details (for example parameters that could > > be > > > > used > > > > > > to > > > > > > > tune Hash aggregation) that could aid QA/documentation. > > > > > > > > > > > > > > What do people think? Can we start enforcing the requirement to > > > have > > > > > > > reviewed design docs before submitting pull requests for > > *advanced* > > > > > > > features? > > > > > > > > > > > > > > Parth > > > > > > > > > > > > > > [1] > http://people.csail.mit.edu/matei/papers/2012/nsdi_spark.pdf > > > > > > > [2] > > > > > > > > > > > > > > > > https://issues.apache.org/jira/secure/attachment/12622804/DrillAggrs.pdf > > > > > > > > > > > > > > > > > > > > > > > > > > > >
