You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hive.apache.org by Lefty Leverenz <le...@gmail.com> on 2017/11/30 01:58:26 UTC
[DISCUSS] Do-it-yourself docs
Hive contributors are responsible for documenting their own commits,
although many seem to be unaware of this or too busy with other tasks. How
can we boost the number of jiras that get documented?
Our current process is to put a TODOC*<release>* label on each committed
issue that needs wiki documentation, then remove it when the doc is done.
But nobody tallies the TODOC labels at release time or pressures
contributors to do their documentation, so we have a large backlog of
unfinished doc tasks.
For several years I've monitored the dev@hive mailing list for issues that
should be documented in the wiki. Whenever a committed patch needs doc and
the contributor hasn't taken care of it, I add a TODOC label and write a
doc note naming new configuration parameters, reserved words, or HiveQL
syntax. (This is convenient for searches.) I also give links to places in
the wiki where the docs belong.
Soon, I'll stop monitoring the Hive mailing lists and writing doc notes.
My time can be better spent doing documentation, instead of just pointing
out that it needs to be done. But I can't tackle the whole backlog, and
many future commits won't even get a TODOC label.
What can we do to improve the Hive doc process?
-- Lefty
Re: [DISCUSS] Do-it-yourself docs
Posted by Lefty Leverenz <le...@gmail.com>.
We have three goals with just a few tools of persuasion.
Goals:
1. Identify JIRA issues that need documentation.
2. Add doc notes or release notes to JIRA issues.
3. Document Hive code and procedures in the wiki. *(main goal)*
I've been helping with #1 and #2, adding ~17 TODOC labels & doc notes a
month, but soon I'll stop that and focus on #3.
Tools:
- TODOC labels
- Yetus checks by Hive QA (?)
- JIRA subtasks (?)
- Education: mailing list, wiki (How to Contribute
<https://cwiki.apache.org/confluence/display/Hive/HowToContribute>, How
to Commit
<https://cwiki.apache.org/confluence/display/Hive/HowToCommit#HowToCommit-Commit>
)
- Nudging: JIRA comments
-- Lefty
On Mon, Dec 4, 2017 at 10:59 AM, Eugene Koifman <ek...@hortonworks.com>
wrote:
> Perhaps this should be a 2 stage process. One to approve the code and one
> to approve the doc.
> It seems odd to update the Wiki (which isn’t tracked using the same Git
> repo as the code) before
> the code changes have been agreed to. Both approvals would be required to
> commit.
>
> Eugene
>
>
> On 12/3/17, 2:49 PM, "Prasanth Jayachandran" <j....@gmail.com>
> wrote:
>
> +1 for Yetus integration to -1 patches without docs.
>
>
> Thanks and Regards,
> Prasanth Jayachandran
>
>
> On Sat, Dec 2, 2017 at 3:04 AM, Klára Barna Zsombor <
> zsomboro@gmail.com>
> wrote:
>
> > Could this be somehow integrated into the Yetus checks? I'm thinking
> that
> > if the Jira being tested does not have one of the "Doc-Performed",
> > "To-Doc", "Doc-Not-Needed" labels then it would get a -1 from Yetus.
> > Peter what do you think? Is Yetus extendable in this way?
> >
> > On Thu, Nov 30, 2017 at 2:58 AM, Lefty Leverenz <
> leftyleverenz@gmail.com>
> > wrote:
> >
> > > Hive contributors are responsible for documenting their own
> commits,
> > > although many seem to be unaware of this or too busy with other
> tasks.
> > How
> > > can we boost the number of jiras that get documented?
> > >
> > >
> > > Our current process is to put a TODOC*<release>* label on each
> committed
> > > issue that needs wiki documentation, then remove it when the doc
> is done.
> > > But nobody tallies the TODOC labels at release time or pressures
> > > contributors to do their documentation, so we have a large backlog
> of
> > > unfinished doc tasks.
> > >
> > >
> > > For several years I've monitored the dev@hive mailing list for
> issues
> > that
> > > should be documented in the wiki. Whenever a committed patch
> needs doc
> > and
> > > the contributor hasn't taken care of it, I add a TODOC label and
> write a
> > > doc note naming new configuration parameters, reserved words, or
> HiveQL
> > > syntax. (This is convenient for searches.) I also give links to
> places
> > in
> > > the wiki where the docs belong.
> > >
> > >
> > > Soon, I'll stop monitoring the Hive mailing lists and writing doc
> notes.
> > > My time can be better spent doing documentation, instead of just
> pointing
> > > out that it needs to be done. But I can't tackle the whole
> backlog, and
> > > many future commits won't even get a TODOC label.
> > >
> > >
> > > What can we do to improve the Hive doc process?
> > >
> > > -- Lefty
> > >
> >
>
>
>
Re: [DISCUSS] Do-it-yourself docs
Posted by Eugene Koifman <ek...@hortonworks.com>.
Perhaps this should be a 2 stage process. One to approve the code and one to approve the doc.
It seems odd to update the Wiki (which isn’t tracked using the same Git repo as the code) before
the code changes have been agreed to. Both approvals would be required to commit.
Eugene
On 12/3/17, 2:49 PM, "Prasanth Jayachandran" <j....@gmail.com> wrote:
+1 for Yetus integration to -1 patches without docs.
Thanks and Regards,
Prasanth Jayachandran
On Sat, Dec 2, 2017 at 3:04 AM, Klára Barna Zsombor <zs...@gmail.com>
wrote:
> Could this be somehow integrated into the Yetus checks? I'm thinking that
> if the Jira being tested does not have one of the "Doc-Performed",
> "To-Doc", "Doc-Not-Needed" labels then it would get a -1 from Yetus.
> Peter what do you think? Is Yetus extendable in this way?
>
> On Thu, Nov 30, 2017 at 2:58 AM, Lefty Leverenz <le...@gmail.com>
> wrote:
>
> > Hive contributors are responsible for documenting their own commits,
> > although many seem to be unaware of this or too busy with other tasks.
> How
> > can we boost the number of jiras that get documented?
> >
> >
> > Our current process is to put a TODOC*<release>* label on each committed
> > issue that needs wiki documentation, then remove it when the doc is done.
> > But nobody tallies the TODOC labels at release time or pressures
> > contributors to do their documentation, so we have a large backlog of
> > unfinished doc tasks.
> >
> >
> > For several years I've monitored the dev@hive mailing list for issues
> that
> > should be documented in the wiki. Whenever a committed patch needs doc
> and
> > the contributor hasn't taken care of it, I add a TODOC label and write a
> > doc note naming new configuration parameters, reserved words, or HiveQL
> > syntax. (This is convenient for searches.) I also give links to places
> in
> > the wiki where the docs belong.
> >
> >
> > Soon, I'll stop monitoring the Hive mailing lists and writing doc notes.
> > My time can be better spent doing documentation, instead of just pointing
> > out that it needs to be done. But I can't tackle the whole backlog, and
> > many future commits won't even get a TODOC label.
> >
> >
> > What can we do to improve the Hive doc process?
> >
> > -- Lefty
> >
>
Re: [DISCUSS] Do-it-yourself docs
Posted by Prasanth Jayachandran <j....@gmail.com>.
+1 for Yetus integration to -1 patches without docs.
Thanks and Regards,
Prasanth Jayachandran
On Sat, Dec 2, 2017 at 3:04 AM, Klára Barna Zsombor <zs...@gmail.com>
wrote:
> Could this be somehow integrated into the Yetus checks? I'm thinking that
> if the Jira being tested does not have one of the "Doc-Performed",
> "To-Doc", "Doc-Not-Needed" labels then it would get a -1 from Yetus.
> Peter what do you think? Is Yetus extendable in this way?
>
> On Thu, Nov 30, 2017 at 2:58 AM, Lefty Leverenz <le...@gmail.com>
> wrote:
>
> > Hive contributors are responsible for documenting their own commits,
> > although many seem to be unaware of this or too busy with other tasks.
> How
> > can we boost the number of jiras that get documented?
> >
> >
> > Our current process is to put a TODOC*<release>* label on each committed
> > issue that needs wiki documentation, then remove it when the doc is done.
> > But nobody tallies the TODOC labels at release time or pressures
> > contributors to do their documentation, so we have a large backlog of
> > unfinished doc tasks.
> >
> >
> > For several years I've monitored the dev@hive mailing list for issues
> that
> > should be documented in the wiki. Whenever a committed patch needs doc
> and
> > the contributor hasn't taken care of it, I add a TODOC label and write a
> > doc note naming new configuration parameters, reserved words, or HiveQL
> > syntax. (This is convenient for searches.) I also give links to places
> in
> > the wiki where the docs belong.
> >
> >
> > Soon, I'll stop monitoring the Hive mailing lists and writing doc notes.
> > My time can be better spent doing documentation, instead of just pointing
> > out that it needs to be done. But I can't tackle the whole backlog, and
> > many future commits won't even get a TODOC label.
> >
> >
> > What can we do to improve the Hive doc process?
> >
> > -- Lefty
> >
>
Re: [DISCUSS] Do-it-yourself docs
Posted by Klára Barna Zsombor <zs...@gmail.com>.
Could this be somehow integrated into the Yetus checks? I'm thinking that
if the Jira being tested does not have one of the "Doc-Performed",
"To-Doc", "Doc-Not-Needed" labels then it would get a -1 from Yetus.
Peter what do you think? Is Yetus extendable in this way?
On Thu, Nov 30, 2017 at 2:58 AM, Lefty Leverenz <le...@gmail.com>
wrote:
> Hive contributors are responsible for documenting their own commits,
> although many seem to be unaware of this or too busy with other tasks. How
> can we boost the number of jiras that get documented?
>
>
> Our current process is to put a TODOC*<release>* label on each committed
> issue that needs wiki documentation, then remove it when the doc is done.
> But nobody tallies the TODOC labels at release time or pressures
> contributors to do their documentation, so we have a large backlog of
> unfinished doc tasks.
>
>
> For several years I've monitored the dev@hive mailing list for issues that
> should be documented in the wiki. Whenever a committed patch needs doc and
> the contributor hasn't taken care of it, I add a TODOC label and write a
> doc note naming new configuration parameters, reserved words, or HiveQL
> syntax. (This is convenient for searches.) I also give links to places in
> the wiki where the docs belong.
>
>
> Soon, I'll stop monitoring the Hive mailing lists and writing doc notes.
> My time can be better spent doing documentation, instead of just pointing
> out that it needs to be done. But I can't tackle the whole backlog, and
> many future commits won't even get a TODOC label.
>
>
> What can we do to improve the Hive doc process?
>
> -- Lefty
>