drill-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "John Omernik (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DRILL-4699) Add Description Column in sys.options
Date Fri, 30 Mar 2018 13:43:00 GMT

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

John Omernik commented on DRILL-4699:

I can't comment on the work/PR being dated. However, I do not think the intended goals are
covered by DRILL-5723.  The main goal is to make it so options are documented when added,
and that documentation is right in the sys.options (or sys.internaloptions even, I was not
aware of the work to make internal options).  Either way, the goal is the same, there should
not be options added where there is a reason why the developer adding the option can't add
a few sentences on what the option is, what it does, and how it works.  There have been too
many times I have to go to the source code to figure out an option.  By adding it here, it
can act as the source of record for all of the options. This could then be utilized downstream
for automatically updating the documentation. (If the sys.options description changes, the
documentation can be auto generated based on it).  



> Add Description Column in sys.options
> -------------------------------------
>                 Key: DRILL-4699
>                 URL: https://issues.apache.org/jira/browse/DRILL-4699
>             Project: Apache Drill
>          Issue Type: Improvement
>          Components:  Server, Documentation
>    Affects Versions: 1.6.0
>            Reporter: John Omernik
>            Assignee: Sudheesh Katkam
>            Priority: Major
> select * from sys.options provides a user with a strong understanding of what options
are available to Drill. These options are not well documented.  Some options are "experimental"
other options have a function only in specific cases (writers vs readers for example).  If
we had a large text field for description, we could enforce documentation of the settings
are option creation time, and the description of the setting could change as the versions
change (i.e. when an option graduates to being supported from being experimental, it would
be changed in the version the user is using. I.e. when they run select * from sys.options,
they know the exact state of the option every time they query. It could also facilitate better
self documentation via QA on pull requests "Did you update the sys.options.desc?"  This makes
it easier for users, and admins in the use of Drill in an enterprise.    
> The first step is adding the field, and then going back and filling in the desc for each
option.  (Another JIRA after the option is available)

This message was sent by Atlassian JIRA

View raw message