Well, if it works for Pig then let's give it a try for Hive. Unless someone has a better idea, of course. (Nudge.) Both javadocs and wikidocs should be strongly encouraged. Also hive-default.xml.template for new config parameters. Anything else?
By the way here's another example of a JIRA that hides its need for documentation: HIVE-4002 <https://issues.apache.org/jira/browse/HIVE-4002>creates config param 'hive.fetch.task.aggr' but doesn't mention it by name anywhere except the patch, so when I did a JIRA search I couldn't find it. I'm not trying to embarrass anyone, it's just that I try to keep track of JIRAs that create user parameters or new syntax, and this one escaped notice until I was researching another hive.fetch.xxx. -- Lefty On Wed, Nov 6, 2013 at 4:44 PM, Thejas Nair <the...@hortonworks.com> wrote: > In case of pig, where the documentation is under same repository and > version controlled, the feature patch is expected to include the > documentation changes as well, or at least documentation in release > notes section that be used to create documentation. > > > > On Wed, Nov 6, 2013 at 12:48 PM, Lefty Leverenz <leftylever...@gmail.com> > wrote: > > What do other projects do? > > > > -- Lefty > > > > > > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <the...@hortonworks.com> > wrote: > > > >> I am fine with a followup doc jira if the enough information to create > >> a document is there in the original jira (in form of release notes > >> section of jira, or jira description etc). There has to be enough > >> information so that people who don't know hive internals can also do > >> the follow up work of updating the docs. > >> > >> But I think committers need to ensure either the doc update is done as > >> part of committing process or a sufficient information is in the jira > >> and there is a follow up 'format the information and update > >> appropriate section in wiki' jira. > >> > >> > >> On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz < > leftylever...@gmail.com> > >> wrote: > >> > Could a new status such as "Just needs doc" be added? Or perhaps a > >> > resolution such as "Undocumented"? Because folks who want to get > their > >> > hands on new features need a way to know when the code is ready, even > if > >> > the doc is missing. > >> > > >> > Sometimes information is available if you know where to look for it > (JIRA > >> > comments & patches, javadocs, tests) or if slides are available from a > >> > presentation. Sometimes tinkering around works, or using the mailing > >> > lists. > >> > > >> > Sure, that's not good enough for general users so pushing for wikidocs > >> > seems like a good idea. But let's not create a limbo of features and > >> fixes > >> > waiting for docs. Unless new doc resources are going to be allocated > >> soon > >> > ... ? <Shameless plug for getting more Hive tech writers.> > >> > > >> > I like the release notes idea. When the doc is too elaborate for > release > >> > notes, a link to the wikidoc could be given. If a design doc has > current > >> > information, that could be noted. If javadocs are sufficient, the > >> classes > >> > could be listed. > >> > > >> > A minor advantage of using a separate doc ticket is that it can be > >> assigned > >> > to a writer or different developer without obscuring the coding > >> > responsibility. And, of course, it boosts the JIRA count for > >> contributors > >> > on the Credits <http://hive.apache.org/credits.html#Contributors> > page > >> > (except that the link is broken). > >> > > >> > > >> > -- Lefty > >> > > >> > > >> > On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <the...@hortonworks.com> > >> wrote: > >> > > >> >> There is no guarantee that the subtask will ever get completed after > >> >> the feature goes in. There is no point of new features if users can't > >> >> actually figure how to use it. > >> >> I think we should either add sufficient documentation in the release > >> >> notes section of jira or add doc in wiki as upcoming feature before > we > >> >> commit the changes. > >> >> > >> >> > >> >> On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman < > >> ekoif...@hortonworks.com> > >> >> wrote: > >> >> > I think opening a separate doc ticket and making it a subtask of > the > >> dev > >> >> > ticket works pretty well. The subtask can contain notes specific > to > >> >> > documentation. > >> >> > > >> >> > Eugene > >> >> > > >> >> > > >> >> > > >> >> > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke < > lars.fran...@gmail.com > >> >> >wrote: > >> >> > > >> >> >> Hi, > >> >> >> > >> >> >> I wanted to ask how people feel about a policy where an issue is > not > >> >> >> closed until documentation has been added to the Wiki? > >> >> >> > >> >> >> Problematic issues fall roughly in two categories: > >> >> >> * They have a generic title (add UDF for XY) an attached patch > and a > >> >> >> few code reviews without ever even mentioning what the name or > usage > >> >> >> of the new UDF is (< > https://issues.apache.org/jira/browse/HIVE-5252 > >> >) > >> >> >> > >> >> >> * They have a design document or description with the intended > syntax > >> >> >> but that's often not the final form so one has to look up the > patch > >> >> >> (can't find a good example right now) > >> >> >> > >> >> >> Both are a lot of work to document for someone who has not > followed > >> >> >> that issue. Tracking undocumented things would be got to not > forget > >> >> >> about it and to have an incentive to do it. > >> >> >> > >> >> >> Obviously not all things need documentation, and not all things > need > >> >> >> to be documented by the person who submitted the patch. But to > make > >> >> >> things easier for documentation people it'd be great if the issue > >> >> >> could contain an up to date description of at least the syntax > >> changes > >> >> >> and configuration options etc. so that we can tidy it up and > transfer > >> >> >> it to the wiki. It's not nice to dig through patches for this. > >> >> >> > >> >> >> Another alternative would be to open issues like "Document > HIVE-5252" > >> >> >> but I like the other option better. > >> >> >> > >> >> >> What do people think? > >> >> >> > >> >> >> Cheers, > >> >> >> Lars > >> >> >> > >> >> > > >> >> > -- > >> >> > CONFIDENTIALITY NOTICE > >> >> > NOTICE: This message is intended for the use of the individual or > >> entity > >> >> to > >> >> > which it is addressed and may contain information that is > >> confidential, > >> >> > privileged and exempt from disclosure under applicable law. If the > >> reader > >> >> > of this message is not the intended recipient, you are hereby > notified > >> >> that > >> >> > any printing, copying, dissemination, distribution, disclosure or > >> >> > forwarding of this communication is strictly prohibited. If you > have > >> >> > received this communication in error, please contact the sender > >> >> immediately > >> >> > and delete it from your system. Thank You. > >> >> > >> >> -- > >> >> CONFIDENTIALITY NOTICE > >> >> NOTICE: This message is intended for the use of the individual or > >> entity to > >> >> which it is addressed and may contain information that is > confidential, > >> >> privileged and exempt from disclosure under applicable law. If the > >> reader > >> >> of this message is not the intended recipient, you are hereby > notified > >> that > >> >> any printing, copying, dissemination, distribution, disclosure or > >> >> forwarding of this communication is strictly prohibited. If you have > >> >> received this communication in error, please contact the sender > >> immediately > >> >> and delete it from your system. Thank You. > >> >> > >> > >> -- > >> CONFIDENTIALITY NOTICE > >> NOTICE: This message is intended for the use of the individual or > entity to > >> which it is addressed and may contain information that is confidential, > >> privileged and exempt from disclosure under applicable law. If the > reader > >> of this message is not the intended recipient, you are hereby notified > that > >> any printing, copying, dissemination, distribution, disclosure or > >> forwarding of this communication is strictly prohibited. If you have > >> received this communication in error, please contact the sender > immediately > >> and delete it from your system. Thank You. > >> > > -- > CONFIDENTIALITY NOTICE > NOTICE: This message is intended for the use of the individual or entity to > which it is addressed and may contain information that is confidential, > privileged and exempt from disclosure under applicable law. If the reader > of this message is not the intended recipient, you are hereby notified that > any printing, copying, dissemination, distribution, disclosure or > forwarding of this communication is strictly prohibited. If you have > received this communication in error, please contact the sender immediately > and delete it from your system. Thank You. >
