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 <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.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 350, Amsterdam, The Netherlands. The Royal Bank of Scotland N.V. and The Royal Bank of Scotland plc are authorised to act as agent for each other in certain jurisdictions. This e-mail message is confidential and for use by the addressee only. If the message is received by anyone other than the addressee, please return the message to the sender by replying to it and then delete the message from your computer. Internet e-mails are not necessarily secure. The Royal Bank of Scotland plc and The Royal Bank of Scotland N.V. including its affiliates ("RBS group") does not accept responsibility for changes made to this message after it was sent. For the protection of RBS group and its clients and customers, and in compliance with regulatory requirements, the contents of both incoming and outgoing e-mail communications, which could include proprietary information and Non-Public Personal Information, may be read by authorised persons within RBS group other than the intended recipient(s). Whilst all reasonable care has been taken to avoid the transmission of viruses, it is the responsibility of the recipient to ensure that the onward transmission, opening or use of this message and any attachments will not adversely affect its systems or data. No responsibility is accepted by the RBS group in this regard and the recipient should carry out such virus and other checks as it considers appropriate. Visit our website at www.rbs.com ***********************************************************************************
