drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Nadeau <jacq...@dremio.com>
Subject Re: [DISCUSS] Design Documents
Date Tue, 20 Oct 2015 21:39:19 GMT
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 <altekrusejason@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 <asinha@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 <parthc@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 <jacques@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 <parthc@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
> > > > >
> > > >
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message