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