Re: [DISCUSS] Design Documents
Zelaine, Welcome to the Drill community! It was great working with you a few years ago (I think some of your contributions are still present in the code base that evolved into Calcite) and look forward to working together again. Julian
Re: [DISCUSS] Design Documents
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 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 > 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 > > 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 > > > 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
Re: [DISCUSS] Design Documents
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 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 > 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 > > 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 di
Re: [DISCUSS] Design Documents
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 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 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 > 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
Re: [DISCUSS] Design Documents
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 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 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
Re: [DISCUSS] Design Documents
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 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 > 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
Re: [DISCUSS] Design Documents
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 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 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 subs
Re: [DISCUSS] Design Documents
On Mon, Oct 19, 2015 at 2:17 AM, wrote: > When working internally here, we write our design docs upfront using > markdown. > ... > I can't say how appropriate this is for an open-source effort. > Well, the whole Drill web-site is done in Mark-down. Design documents could easily be done as pull requests against that and commenting would be easy.
Re: [DISCUSS] Design Documents
On Sun, Oct 18, 2015 at 4:44 PM, Jacques Nadeau 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 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 > > >
RE: [DISCUSS] Design Documents
Hi - this is always a challenge, when people just love writing code. When working internally here, we write our design docs upfront using markdown. Then we raise a pull request in Stash into the design docs folder. At this point the team comments on the PR, just as they would on a code change. The doc gets tweaked accordingly, then people start coding on the feature branch, where the first merged commit contains the design doc, so the approval cycle kicks in. I think there's something about the social aspects of the review comments that get people more engaged. Also, the review and authoring tools are those the devs are most comfortable working with, so reduced friction. I can't say how appropriate this is for an open-source effort. Regards, Mike -Original Message- From: Jacques Nadeau [mailto:jacq...@dremio.com] Sent: 19 October 2015 00:44 To: dev@drill.apache.org Subject: Re: [DISCUSS] Design Documents 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 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.p > df > *** The Royal Bank of Scotland plc. Registered in Scotland No 90312. Registered Office: 36 St Andrew Square, Edinburgh EH2 2YB. Authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and Prudential Regulation Authority. The Royal Bank of Scotland N.V. is authorised and regulated by the De Nederlandsche Bank and has its seat at Amsterdam, the Netherlands, and is registered in the Commercial Register under number 33002587. Registered Office: Gustav Mahlerlaan 35
Re: [DISCUSS] Design Documents
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 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 >
Re: [DISCUSS] Design Documents
+1 From: Parth Chandra To: dev@drill.apache.org Sent: Friday, October 16, 2015 10:21 AM Subject: [DISCUSS] Design Documents 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
Re: [DISCUSS] Design Documents
Absolutely - yes. I already started following this practice, per Jacques' recommendation. See and embedded Google Doc in comments: https://issues.apache.org/jira/browse/DRILL-3738 Maybe we should use Github wiki or some Google Docs repository to record these design docs centrally. On Fri, Oct 16, 2015 at 1:21 PM, Parth Chandra 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 >
[DISCUSS] Design Documents
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
