[jira] [Commented] (DRILL-1904) Add source documentation on Java packages

["Jason Altekruse (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DRILL-1904?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14274315#comment-14274315 ] 

Jason Altekruse commented on DRILL-1904:
----------------------------------------

I think it might be a bit of a mess to try to name the patches well for this JIRA. Generally we have a single code change (possibly multiple iterations) attached to one JIRA.

As a single unit of work in this case will likely involve documenting several packages, trying to describe the changes in the patch names might be hard. Enforcing one patch per high level package, like say DRILL-1904-exec-compile, might be too restrictive, as we want to encourage writing documentation without too much administration headache, and someone might not want to do all of the docs for a package in a small timeframe. If someone writes docs we should have them reviewed and get them in ASAP, there is no reason to wait to have it merged and be forced to resolve conflicts.

With these considerations in mind, I propose the following: have the patches named by an author (JIRA username for uniqueness), a 'batch' and a version number. Something like Drill-1904-jaltekruse-batch1-v1.patch, where the docs written in a day or two at batched together and uploaded for review, after a review the same set of docs can be re-uploaded to the JIRA and the respective review board with a v2 distinction.

> Add source documentation on Java packages
> -----------------------------------------
>
>                 Key: DRILL-1904
>                 URL: https://issues.apache.org/jira/browse/DRILL-1904
>             Project: Apache Drill
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Jason Altekruse
>             Fix For: Future
>
>         Attachments: DRILL-1904-package-level-docs.patch
>
>
> The Drill codebase needs more documentation to allow new contributors to dive into fixing issues and implementing new features. We will be starting this effort by providing package level documentation for the packages in Drill and then move onto class level documentation on major interfaces.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)