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 <ekoif...@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.prasant...@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 < > zsomb...@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 < > leftylever...@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 > > > > > > > >
