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 > > > > > > > > > > > > > > > > > > > > >
