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