hive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thejas Nair <the...@hortonworks.com>
Subject Re: Documentation Policy
Date Tue, 10 Jun 2014 15:25:11 GMT
TODOC14 sounds good. But I think it should be a label in the labels
field of the jira (it would auto-complete and people are less likely
to use wrong keyword)
We should still ask developers to fill out the release notes section
with sufficient information for creating documentation for it. We
should document this in how-to-contribute wiki page, once we agree on
this.

Also, I don't think we need to wait for end of the release cycle to
start documenting features for the next release. We can document it
saying that something like "for upcoming 0.14 release".


On Tue, Jun 10, 2014 at 2:45 AM, Lefty Leverenz <leftyleverenz@gmail.com> wrote:
> Let's reopen this discussion.  Brock asked in HIVE-7140
> <https://issues.apache.org/jira/browse/HIVE-7140?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14025258#comment-14025258>
> how we can make sure the user docs get updated for jiras committed for
> release 0.14 ("I wonder if we should put a TODO in the release notes so it
> can be easily pulled for the 0.14 release?").
>
> In many cases, a release note can contain all the doc information or a
> pointer to it.  But sometimes it's more complicated.  In any case, can we
> agree on a standard phrase such as TODO or DOC14 to put in the release note
> so it's easy to find jiras that need user docs when the time comes?
>
> Presumably the doc flag would be removed from the release note as soon as
> the wiki has been updated.  But realistically, some jiras wouldn't get
> documented in time for the release.  So should those jiras get listed
> somewhere at release time and have their doc flag removed, or do we want
> the world to see what's unfinished in the release notes?
>
> -- Lefty
>
>
> On Sat, Nov 9, 2013 at 11:59 PM, Lefty Leverenz <leftyleverenz@gmail.com>
> wrote:
>
>> 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 <thejas@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 <leftyleverenz@gmail.com>
>>> wrote:
>>> > What do other projects do?
>>> >
>>> > -- Lefty
>>> >
>>> >
>>> > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <thejas@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 <
>>> leftyleverenz@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 <thejas@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 <
>>> >> ekoifman@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.francke@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.
>>>
>>
>>

-- 
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.

Mime
View raw message