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