You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hive.apache.org by Lars Francke <la...@gmail.com> on 2013/11/05 09:16:18 UTC
Documentation Policy
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
Re: Documentation Policy
Posted by Eugene Koifman <ek...@hortonworks.com>.
Another advantage of separate doc ticket is that when we are making a
release it's easier to tell what has been checked in already and what else
needs to be done and whether we should hold the release due to doc issues
or not. Release notes are only useful for people who already have a lot of
experience with the product.
Eugene
On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz <le...@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 <th...@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.
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
> Slightly tangential but how we do choose on adding this to some of the
> already resolved JIRAs that are missing documentation? I can volunteer to
> dig through our JIRA queue and find some of these out but probably would
> need some help from the contributors on these to be sure that they are
> doc'ed properly. :)
Feel free to label such jiras with this keyword and ask the
contributors for more information if you need any.
--
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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
>
> Should we create JIRA for these so that the work to be done on these does
> not get lost?
... or should we schedule a doc blitz to take care of as many as possible
right away? (Inclusive OR.)
-- Lefty
On Sat, Jun 14, 2014 at 10:35 PM, kulkarni.swarnim@gmail.com <
kulkarni.swarnim@gmail.com> wrote:
> A few more from older releases:
>
> *0.10*:
>
> https://issues.apache.org/jira/browse/HIVE-2397?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC10%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
>
> *0.11:*
>
> https://issues.apache.org/jira/browse/HIVE-3073?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC11%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
>
> *0.12:*
>
> https://issues.apache.org/jira/browse/HIVE-5161?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC12%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
>
> Should we create JIRA for these so that the work to be done on these does
> not get lost?
>
>
>
> On Fri, Jun 13, 2014 at 5:59 PM, Lefty Leverenz <le...@gmail.com>
> wrote:
>
> > Agreed, deleting TODOC## simplifies the labels field, so we should just
> use
> > comments to keep track of docs done.
> >
> > Besides, doc tasks can get complicated -- my gmail inbox has a few
> messages
> > with simultaneous done and to-do labels -- so comments are best for
> > tracking progress. Also, as Szehon noticed, links in the comments make
> it
> > easy to find the docs.
> >
> > +1 on (a): delete TODOCs when done; don't add any new labels.
> >
> > -- Lefty
> >
> >
> > On Fri, Jun 13, 2014 at 1:31 PM, kulkarni.swarnim@gmail.com <
> > kulkarni.swarnim@gmail.com> wrote:
> >
> > > +1 on deleting the TODOC tag as I think it's assumed by default that
> once
> > > an enhancement is done, it will be doc'ed. We may consider adding an
> > > additional "docdone" tag but I think we can instead just wait for a +1
> > from
> > > the contributor that the documentation is satisfactory (and assume a
> > > implicit +1 for no reply) before deleting the TODOC tag.
> > >
> > >
> > > On Fri, Jun 13, 2014 at 1:32 PM, Szehon Ho <sz...@cloudera.com>
> wrote:
> > >
> > > > Yea, I'd imagine the TODOC tag pollutes the query of TODOC's and
> > confuses
> > > > the state of a JIRA, so its probably best to remove it.
> > > >
> > > > The idea of "docdone" is to query what docs got produced and needs
> > > review?
> > > > It might be nice to have a tag for that, to easily signal to
> > contributor
> > > > or interested parties to take a look.
> > > >
> > > > On a side note, I already find very helpful your JIRA comments with
> > links
> > > > to doc-wikis, both to inform the contributor and just as reference
> for
> > > > others. Thanks again for the great work.
> > > >
> > > >
> > > > On Fri, Jun 13, 2014 at 1:33 AM, Lefty Leverenz <
> > leftyleverenz@gmail.com
> > > >
> > > > wrote:
> > > >
> > > > > One more question: what should we do after the documentation is
> done
> > > > for a
> > > > > JIRA ticket?
> > > > >
> > > > > (a) Just remove the TODOC## label.
> > > > > (b) Replace TODOC## with docdone (no caps, no version number).
> > > > > (c) Add a docdone label but keep TODOC##.
> > > > > (d) Something else.
> > > > >
> > > > >
> > > > > -- Lefty
> > > > >
> > > > >
> > > > > On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <brock@cloudera.com
> >
> > > > wrote:
> > > > >
> > > > > > Thank you guys! This is great work.
> > > > > >
> > > > > >
> > > > > > On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> > > > > > kulkarni.swarnim@gmail.com> wrote:
> > > > > >
> > > > > > > Going through the issues, I think overall Lefty did an awesome
> > job
> > > > > > catching
> > > > > > > and documenting most of them in time. Following are some of the
> > > 0.13
> > > > > and
> > > > > > > 0.14 ones which I found which either do not have documentation
> or
> > > > have
> > > > > > > outdated one and probably need one to be consumeable.
> > Contributors,
> > > > > feel
> > > > > > > free to remove the label if you disagree.
> > > > > > >
> > > > > > > *TODOC13:*
> > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > > > >
> > > > > > > *TODOC14:*
> > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > > > >
> > > > > > > I'll continue digging through the queue going backwards to 0.12
> > and
> > > > > 0.11
> > > > > > > and see if I find similar stuff there as well.
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > > > > > > kulkarni.swarnim@gmail.com> wrote:
> > > > > > >
> > > > > > > > > Feel free to label such jiras with this keyword and ask the
> > > > > > > contributors
> > > > > > > > for more information if you need any.
> > > > > > > >
> > > > > > > > Cool. I'll start chugging through the queue today adding
> labels
> > > as
> > > > > apt.
> > > > > > > >
> > > > > > > >
> > > > > > > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <
> > > > thejas@hortonworks.com
> > > > > >
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > > > > > > >> Sounds good to me.
> > > > > > > >>
> > > > > > > >> --
> > > > > > > >> 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.
> > > > > > > >>
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > --
> > > > > > > > Swarnim
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > Swarnim
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> > >
> > >
> > > --
> > > Swarnim
> > >
> >
>
>
>
> --
> Swarnim
>
Re: Documentation Policy
Posted by "kulkarni.swarnim@gmail.com" <ku...@gmail.com>.
A few more from older releases:
*0.10*:
https://issues.apache.org/jira/browse/HIVE-2397?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC10%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
*0.11:*
https://issues.apache.org/jira/browse/HIVE-3073?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC11%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
*0.12:*
https://issues.apache.org/jira/browse/HIVE-5161?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC12%20AND%20status%20in%20(Resolved%2C%20Closed)%20ORDER%20BY%20priority%20DESC
Should we create JIRA for these so that the work to be done on these does
not get lost?
On Fri, Jun 13, 2014 at 5:59 PM, Lefty Leverenz <le...@gmail.com>
wrote:
> Agreed, deleting TODOC## simplifies the labels field, so we should just use
> comments to keep track of docs done.
>
> Besides, doc tasks can get complicated -- my gmail inbox has a few messages
> with simultaneous done and to-do labels -- so comments are best for
> tracking progress. Also, as Szehon noticed, links in the comments make it
> easy to find the docs.
>
> +1 on (a): delete TODOCs when done; don't add any new labels.
>
> -- Lefty
>
>
> On Fri, Jun 13, 2014 at 1:31 PM, kulkarni.swarnim@gmail.com <
> kulkarni.swarnim@gmail.com> wrote:
>
> > +1 on deleting the TODOC tag as I think it's assumed by default that once
> > an enhancement is done, it will be doc'ed. We may consider adding an
> > additional "docdone" tag but I think we can instead just wait for a +1
> from
> > the contributor that the documentation is satisfactory (and assume a
> > implicit +1 for no reply) before deleting the TODOC tag.
> >
> >
> > On Fri, Jun 13, 2014 at 1:32 PM, Szehon Ho <sz...@cloudera.com> wrote:
> >
> > > Yea, I'd imagine the TODOC tag pollutes the query of TODOC's and
> confuses
> > > the state of a JIRA, so its probably best to remove it.
> > >
> > > The idea of "docdone" is to query what docs got produced and needs
> > review?
> > > It might be nice to have a tag for that, to easily signal to
> contributor
> > > or interested parties to take a look.
> > >
> > > On a side note, I already find very helpful your JIRA comments with
> links
> > > to doc-wikis, both to inform the contributor and just as reference for
> > > others. Thanks again for the great work.
> > >
> > >
> > > On Fri, Jun 13, 2014 at 1:33 AM, Lefty Leverenz <
> leftyleverenz@gmail.com
> > >
> > > wrote:
> > >
> > > > One more question: what should we do after the documentation is done
> > > for a
> > > > JIRA ticket?
> > > >
> > > > (a) Just remove the TODOC## label.
> > > > (b) Replace TODOC## with docdone (no caps, no version number).
> > > > (c) Add a docdone label but keep TODOC##.
> > > > (d) Something else.
> > > >
> > > >
> > > > -- Lefty
> > > >
> > > >
> > > > On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <br...@cloudera.com>
> > > wrote:
> > > >
> > > > > Thank you guys! This is great work.
> > > > >
> > > > >
> > > > > On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> > > > > kulkarni.swarnim@gmail.com> wrote:
> > > > >
> > > > > > Going through the issues, I think overall Lefty did an awesome
> job
> > > > > catching
> > > > > > and documenting most of them in time. Following are some of the
> > 0.13
> > > > and
> > > > > > 0.14 ones which I found which either do not have documentation or
> > > have
> > > > > > outdated one and probably need one to be consumeable.
> Contributors,
> > > > feel
> > > > > > free to remove the label if you disagree.
> > > > > >
> > > > > > *TODOC13:*
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > > >
> > > > > > *TODOC14:*
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > > >
> > > > > > I'll continue digging through the queue going backwards to 0.12
> and
> > > > 0.11
> > > > > > and see if I find similar stuff there as well.
> > > > > >
> > > > > >
> > > > > >
> > > > > > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > > > > > kulkarni.swarnim@gmail.com> wrote:
> > > > > >
> > > > > > > > Feel free to label such jiras with this keyword and ask the
> > > > > > contributors
> > > > > > > for more information if you need any.
> > > > > > >
> > > > > > > Cool. I'll start chugging through the queue today adding labels
> > as
> > > > apt.
> > > > > > >
> > > > > > >
> > > > > > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <
> > > thejas@hortonworks.com
> > > > >
> > > > > > > wrote:
> > > > > > >
> > > > > > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > > > > > >> Sounds good to me.
> > > > > > >>
> > > > > > >> --
> > > > > > >> 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.
> > > > > > >>
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > --
> > > > > > > Swarnim
> > > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > Swarnim
> > > > > >
> > > > >
> > > >
> > >
> >
> >
> >
> > --
> > Swarnim
> >
>
--
Swarnim
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
Agreed, deleting TODOC## simplifies the labels field, so we should just use
comments to keep track of docs done.
Besides, doc tasks can get complicated -- my gmail inbox has a few messages
with simultaneous done and to-do labels -- so comments are best for
tracking progress. Also, as Szehon noticed, links in the comments make it
easy to find the docs.
+1 on (a): delete TODOCs when done; don't add any new labels.
-- Lefty
On Fri, Jun 13, 2014 at 1:31 PM, kulkarni.swarnim@gmail.com <
kulkarni.swarnim@gmail.com> wrote:
> +1 on deleting the TODOC tag as I think it's assumed by default that once
> an enhancement is done, it will be doc'ed. We may consider adding an
> additional "docdone" tag but I think we can instead just wait for a +1 from
> the contributor that the documentation is satisfactory (and assume a
> implicit +1 for no reply) before deleting the TODOC tag.
>
>
> On Fri, Jun 13, 2014 at 1:32 PM, Szehon Ho <sz...@cloudera.com> wrote:
>
> > Yea, I'd imagine the TODOC tag pollutes the query of TODOC's and confuses
> > the state of a JIRA, so its probably best to remove it.
> >
> > The idea of "docdone" is to query what docs got produced and needs
> review?
> > It might be nice to have a tag for that, to easily signal to contributor
> > or interested parties to take a look.
> >
> > On a side note, I already find very helpful your JIRA comments with links
> > to doc-wikis, both to inform the contributor and just as reference for
> > others. Thanks again for the great work.
> >
> >
> > On Fri, Jun 13, 2014 at 1:33 AM, Lefty Leverenz <leftyleverenz@gmail.com
> >
> > wrote:
> >
> > > One more question: what should we do after the documentation is done
> > for a
> > > JIRA ticket?
> > >
> > > (a) Just remove the TODOC## label.
> > > (b) Replace TODOC## with docdone (no caps, no version number).
> > > (c) Add a docdone label but keep TODOC##.
> > > (d) Something else.
> > >
> > >
> > > -- Lefty
> > >
> > >
> > > On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <br...@cloudera.com>
> > wrote:
> > >
> > > > Thank you guys! This is great work.
> > > >
> > > >
> > > > On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> > > > kulkarni.swarnim@gmail.com> wrote:
> > > >
> > > > > Going through the issues, I think overall Lefty did an awesome job
> > > > catching
> > > > > and documenting most of them in time. Following are some of the
> 0.13
> > > and
> > > > > 0.14 ones which I found which either do not have documentation or
> > have
> > > > > outdated one and probably need one to be consumeable. Contributors,
> > > feel
> > > > > free to remove the label if you disagree.
> > > > >
> > > > > *TODOC13:*
> > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > >
> > > > > *TODOC14:*
> > > > >
> > > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > > >
> > > > > I'll continue digging through the queue going backwards to 0.12 and
> > > 0.11
> > > > > and see if I find similar stuff there as well.
> > > > >
> > > > >
> > > > >
> > > > > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > > > > kulkarni.swarnim@gmail.com> wrote:
> > > > >
> > > > > > > Feel free to label such jiras with this keyword and ask the
> > > > > contributors
> > > > > > for more information if you need any.
> > > > > >
> > > > > > Cool. I'll start chugging through the queue today adding labels
> as
> > > apt.
> > > > > >
> > > > > >
> > > > > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <
> > thejas@hortonworks.com
> > > >
> > > > > > wrote:
> > > > > >
> > > > > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > > > > >> Sounds good to me.
> > > > > >>
> > > > > >> --
> > > > > >> 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.
> > > > > >>
> > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > Swarnim
> > > > > >
> > > > >
> > > > >
> > > > >
> > > > > --
> > > > > Swarnim
> > > > >
> > > >
> > >
> >
>
>
>
> --
> Swarnim
>
Re: Documentation Policy
Posted by "kulkarni.swarnim@gmail.com" <ku...@gmail.com>.
+1 on deleting the TODOC tag as I think it's assumed by default that once
an enhancement is done, it will be doc'ed. We may consider adding an
additional "docdone" tag but I think we can instead just wait for a +1 from
the contributor that the documentation is satisfactory (and assume a
implicit +1 for no reply) before deleting the TODOC tag.
On Fri, Jun 13, 2014 at 1:32 PM, Szehon Ho <sz...@cloudera.com> wrote:
> Yea, I'd imagine the TODOC tag pollutes the query of TODOC's and confuses
> the state of a JIRA, so its probably best to remove it.
>
> The idea of "docdone" is to query what docs got produced and needs review?
> It might be nice to have a tag for that, to easily signal to contributor
> or interested parties to take a look.
>
> On a side note, I already find very helpful your JIRA comments with links
> to doc-wikis, both to inform the contributor and just as reference for
> others. Thanks again for the great work.
>
>
> On Fri, Jun 13, 2014 at 1:33 AM, Lefty Leverenz <le...@gmail.com>
> wrote:
>
> > One more question: what should we do after the documentation is done
> for a
> > JIRA ticket?
> >
> > (a) Just remove the TODOC## label.
> > (b) Replace TODOC## with docdone (no caps, no version number).
> > (c) Add a docdone label but keep TODOC##.
> > (d) Something else.
> >
> >
> > -- Lefty
> >
> >
> > On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <br...@cloudera.com>
> wrote:
> >
> > > Thank you guys! This is great work.
> > >
> > >
> > > On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> > > kulkarni.swarnim@gmail.com> wrote:
> > >
> > > > Going through the issues, I think overall Lefty did an awesome job
> > > catching
> > > > and documenting most of them in time. Following are some of the 0.13
> > and
> > > > 0.14 ones which I found which either do not have documentation or
> have
> > > > outdated one and probably need one to be consumeable. Contributors,
> > feel
> > > > free to remove the label if you disagree.
> > > >
> > > > *TODOC13:*
> > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > >
> > > > *TODOC14:*
> > > >
> > > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> > > >
> > > > I'll continue digging through the queue going backwards to 0.12 and
> > 0.11
> > > > and see if I find similar stuff there as well.
> > > >
> > > >
> > > >
> > > > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > > > kulkarni.swarnim@gmail.com> wrote:
> > > >
> > > > > > Feel free to label such jiras with this keyword and ask the
> > > > contributors
> > > > > for more information if you need any.
> > > > >
> > > > > Cool. I'll start chugging through the queue today adding labels as
> > apt.
> > > > >
> > > > >
> > > > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <
> thejas@hortonworks.com
> > >
> > > > > wrote:
> > > > >
> > > > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > > > >> Sounds good to me.
> > > > >>
> > > > >> --
> > > > >> 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.
> > > > >>
> > > > >
> > > > >
> > > > >
> > > > > --
> > > > > Swarnim
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Swarnim
> > > >
> > >
> >
>
--
Swarnim
Re: Documentation Policy
Posted by Szehon Ho <sz...@cloudera.com>.
Yea, I'd imagine the TODOC tag pollutes the query of TODOC's and confuses
the state of a JIRA, so its probably best to remove it.
The idea of "docdone" is to query what docs got produced and needs review?
It might be nice to have a tag for that, to easily signal to contributor
or interested parties to take a look.
On a side note, I already find very helpful your JIRA comments with links
to doc-wikis, both to inform the contributor and just as reference for
others. Thanks again for the great work.
On Fri, Jun 13, 2014 at 1:33 AM, Lefty Leverenz <le...@gmail.com>
wrote:
> One more question: what should we do after the documentation is done for a
> JIRA ticket?
>
> (a) Just remove the TODOC## label.
> (b) Replace TODOC## with docdone (no caps, no version number).
> (c) Add a docdone label but keep TODOC##.
> (d) Something else.
>
>
> -- Lefty
>
>
> On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <br...@cloudera.com> wrote:
>
> > Thank you guys! This is great work.
> >
> >
> > On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> > kulkarni.swarnim@gmail.com> wrote:
> >
> > > Going through the issues, I think overall Lefty did an awesome job
> > catching
> > > and documenting most of them in time. Following are some of the 0.13
> and
> > > 0.14 ones which I found which either do not have documentation or have
> > > outdated one and probably need one to be consumeable. Contributors,
> feel
> > > free to remove the label if you disagree.
> > >
> > > *TODOC13:*
> > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> > >
> > > *TODOC14:*
> > >
> > >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> > >
> > > I'll continue digging through the queue going backwards to 0.12 and
> 0.11
> > > and see if I find similar stuff there as well.
> > >
> > >
> > >
> > > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > > kulkarni.swarnim@gmail.com> wrote:
> > >
> > > > > Feel free to label such jiras with this keyword and ask the
> > > contributors
> > > > for more information if you need any.
> > > >
> > > > Cool. I'll start chugging through the queue today adding labels as
> apt.
> > > >
> > > >
> > > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <thejas@hortonworks.com
> >
> > > > wrote:
> > > >
> > > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > > >> Sounds good to me.
> > > >>
> > > >> --
> > > >> 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.
> > > >>
> > > >
> > > >
> > > >
> > > > --
> > > > Swarnim
> > > >
> > >
> > >
> > >
> > > --
> > > Swarnim
> > >
> >
>
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
One more question: what should we do after the documentation is done for a
JIRA ticket?
(a) Just remove the TODOC## label.
(b) Replace TODOC## with docdone (no caps, no version number).
(c) Add a docdone label but keep TODOC##.
(d) Something else.
-- Lefty
On Thu, Jun 12, 2014 at 12:54 PM, Brock Noland <br...@cloudera.com> wrote:
> Thank you guys! This is great work.
>
>
> On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
> kulkarni.swarnim@gmail.com> wrote:
>
> > Going through the issues, I think overall Lefty did an awesome job
> catching
> > and documenting most of them in time. Following are some of the 0.13 and
> > 0.14 ones which I found which either do not have documentation or have
> > outdated one and probably need one to be consumeable. Contributors, feel
> > free to remove the label if you disagree.
> >
> > *TODOC13:*
> >
> >
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
> >
> > *TODOC14:*
> >
> >
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
> >
> > I'll continue digging through the queue going backwards to 0.12 and 0.11
> > and see if I find similar stuff there as well.
> >
> >
> >
> > On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> > kulkarni.swarnim@gmail.com> wrote:
> >
> > > > Feel free to label such jiras with this keyword and ask the
> > contributors
> > > for more information if you need any.
> > >
> > > Cool. I'll start chugging through the queue today adding labels as apt.
> > >
> > >
> > > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <th...@hortonworks.com>
> > > wrote:
> > >
> > >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> > >> Sounds good to me.
> > >>
> > >> --
> > >> 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.
> > >>
> > >
> > >
> > >
> > > --
> > > Swarnim
> > >
> >
> >
> >
> > --
> > Swarnim
> >
>
Re: Documentation Policy
Posted by Brock Noland <br...@cloudera.com>.
Thank you guys! This is great work.
On Wed, Jun 11, 2014 at 6:20 PM, kulkarni.swarnim@gmail.com <
kulkarni.swarnim@gmail.com> wrote:
> Going through the issues, I think overall Lefty did an awesome job catching
> and documenting most of them in time. Following are some of the 0.13 and
> 0.14 ones which I found which either do not have documentation or have
> outdated one and probably need one to be consumeable. Contributors, feel
> free to remove the label if you disagree.
>
> *TODOC13:*
>
> https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
>
> *TODOC14:*
>
> https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
>
> I'll continue digging through the queue going backwards to 0.12 and 0.11
> and see if I find similar stuff there as well.
>
>
>
> On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
> kulkarni.swarnim@gmail.com> wrote:
>
> > > Feel free to label such jiras with this keyword and ask the
> contributors
> > for more information if you need any.
> >
> > Cool. I'll start chugging through the queue today adding labels as apt.
> >
> >
> > On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <th...@hortonworks.com>
> > wrote:
> >
> >> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> >> Sounds good to me.
> >>
> >> --
> >> 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.
> >>
> >
> >
> >
> > --
> > Swarnim
> >
>
>
>
> --
> Swarnim
>
Re: Documentation Policy
Posted by "kulkarni.swarnim@gmail.com" <ku...@gmail.com>.
Going through the issues, I think overall Lefty did an awesome job catching
and documenting most of them in time. Following are some of the 0.13 and
0.14 ones which I found which either do not have documentation or have
outdated one and probably need one to be consumeable. Contributors, feel
free to remove the label if you disagree.
*TODOC13:*
https://issues.apache.org/jira/browse/HIVE-6827?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC13%20AND%20status%20in%20(Resolved%2C%20Closed)
*TODOC14:*
https://issues.apache.org/jira/browse/HIVE-6999?jql=project%20%3D%20HIVE%20AND%20labels%20%3D%20TODOC14%20AND%20status%20in%20(Resolved%2C%20Closed)
I'll continue digging through the queue going backwards to 0.12 and 0.11
and see if I find similar stuff there as well.
On Wed, Jun 11, 2014 at 10:36 AM, kulkarni.swarnim@gmail.com <
kulkarni.swarnim@gmail.com> wrote:
> > Feel free to label such jiras with this keyword and ask the contributors
> for more information if you need any.
>
> Cool. I'll start chugging through the queue today adding labels as apt.
>
>
> On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <th...@hortonworks.com>
> wrote:
>
>> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
>> Sounds good to me.
>>
>> --
>> 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.
>>
>
>
>
> --
> Swarnim
>
--
Swarnim
Re: Documentation Policy
Posted by "kulkarni.swarnim@gmail.com" <ku...@gmail.com>.
> Feel free to label such jiras with this keyword and ask the contributors
for more information if you need any.
Cool. I'll start chugging through the queue today adding labels as apt.
On Tue, Jun 10, 2014 at 9:45 PM, Thejas Nair <th...@hortonworks.com> wrote:
> > Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
> Sounds good to me.
>
> --
> 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.
>
--
Swarnim
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
> Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
Sounds good to me.
--
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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
I can dig through my backlog and add TODOC13 or TODOC14 to a bunch of
issues. Some are even earlier than Hive 0.13 ... sigh!
If you're digging through the JIRA queue, I suggest starting with the
0.13.0 and 0.13.1 release lists. Check the end of the comments to see if I
(or anyone) said the doc was done.
Shall we lump 0.13.0 and 0.13.1 doc tasks as TODOC13?
-- Lefty
On Tue, Jun 10, 2014 at 3:56 PM, kulkarni.swarnim@gmail.com <
kulkarni.swarnim@gmail.com> wrote:
> > Writing documentation sooner rather than later is likely to increases the
> chances of things getting documented.
>
> Big +1 on this. I think documentation contributes towards one of the major
> technical debts(I personally have quite a bit for the patches I
> contributed). IMHO committers may choose to reject patches that don't have
> usage documentation if they include significant work which practically
> cannot be consumed without proper documentation.
>
> Slightly tangential but how we do choose on adding this to some of the
> already resolved JIRAs that are missing documentation? I can volunteer to
> dig through our JIRA queue and find some of these out but probably would
> need some help from the contributors on these to be sure that they are
> doc'ed properly. :)
>
>
> On Tue, Jun 10, 2014 at 5:33 PM, Thejas Nair <th...@hortonworks.com>
> wrote:
>
> > > Also, I don't think we need to wait for end of the release cycle to
> start
> > >> documenting features for the next release.
> > >
> > >
> > > Agreed, but I think we should wait until the next release is less than
> > two
> > > months away. What do other people think?
> >
> > We have been releasing almost every 3-4 months. So that is the longest
> > un-released version documentation would be in the docs.
> > Writing documentation sooner rather than later is likely to increases
> > the chances of things getting documented. It is easier to get details
> > from developers while the details are still fresh in their minds. It
> > would also even the load on documentation volunteers over the time.
> >
> > --
> > 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.
> >
>
>
>
> --
> Swarnim
>
Re: Documentation Policy
Posted by "kulkarni.swarnim@gmail.com" <ku...@gmail.com>.
> Writing documentation sooner rather than later is likely to increases the
chances of things getting documented.
Big +1 on this. I think documentation contributes towards one of the major
technical debts(I personally have quite a bit for the patches I
contributed). IMHO committers may choose to reject patches that don't have
usage documentation if they include significant work which practically
cannot be consumed without proper documentation.
Slightly tangential but how we do choose on adding this to some of the
already resolved JIRAs that are missing documentation? I can volunteer to
dig through our JIRA queue and find some of these out but probably would
need some help from the contributors on these to be sure that they are
doc'ed properly. :)
On Tue, Jun 10, 2014 at 5:33 PM, Thejas Nair <th...@hortonworks.com> wrote:
> > Also, I don't think we need to wait for end of the release cycle to start
> >> documenting features for the next release.
> >
> >
> > Agreed, but I think we should wait until the next release is less than
> two
> > months away. What do other people think?
>
> We have been releasing almost every 3-4 months. So that is the longest
> un-released version documentation would be in the docs.
> Writing documentation sooner rather than later is likely to increases
> the chances of things getting documented. It is easier to get details
> from developers while the details are still fresh in their minds. It
> would also even the load on documentation volunteers over the time.
>
> --
> 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.
>
--
Swarnim
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
> Also, I don't think we need to wait for end of the release cycle to start
>> documenting features for the next release.
>
>
> Agreed, but I think we should wait until the next release is less than two
> months away. What do other people think?
We have been releasing almost every 3-4 months. So that is the longest
un-released version documentation would be in the docs.
Writing documentation sooner rather than later is likely to increases
the chances of things getting documented. It is easier to get details
from developers while the details are still fresh in their minds. It
would also even the load on documentation volunteers over the time.
--
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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
Thanks, Thejas.
TODOC14 sounds good. But I think it should be a label in the labels field
> of the jira ...
An advantage of labels is that they won't show up in the published release
notes.
Also, I don't think we need to wait for end of the release cycle to start
> documenting features for the next release.
Agreed, but I think we should wait until the next release is less than two
months away. What do other people think?
One exception would be significant bug fixes, which the wiki can document
immediately as fixed in the next release with a link to the Jira. That way
people will find out about the bug and can try applying the patch. (Of
course they can also find out directly in the Jira, or in the hive-dev
mailing list, but we want to make the wiki more useful.)
A possible problem is if the next release gets a different number, such as
0.13.2 or 1.0.0. But it's easy enough to grep through an exported copy of
the wiki to find all instances of "0.14" and change them to the new number.
-- Lefty
On Tue, Jun 10, 2014 at 8:25 AM, Thejas Nair <th...@hortonworks.com> wrote:
> 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 <le...@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 <th...@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 <th...@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.
>
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
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 <le...@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 <le...@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 <th...@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 <le...@gmail.com>
>>> wrote:
>>> > What do other projects do?
>>> >
>>> > -- Lefty
>>> >
>>> >
>>> > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <th...@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 <th...@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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
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 <le...@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 <th...@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 <le...@gmail.com>
>> wrote:
>> > What do other projects do?
>> >
>> > -- Lefty
>> >
>> >
>> > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <th...@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 <th...@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.
>>
>
>
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
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 <th...@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 <le...@gmail.com>
> wrote:
> > What do other projects do?
> >
> > -- Lefty
> >
> >
> > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <th...@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 <th...@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.
>
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
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 <le...@gmail.com> wrote:
> What do other projects do?
>
> -- Lefty
>
>
> On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <th...@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 <le...@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 <th...@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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
What do other projects do?
-- Lefty
On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <th...@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 <le...@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 <th...@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.
>
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
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 <le...@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 <th...@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 <ek...@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.
Re: Documentation Policy
Posted by Lefty Leverenz <le...@gmail.com>.
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 <th...@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 <ek...@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.
>
Re: Documentation Policy
Posted by Thejas Nair <th...@hortonworks.com>.
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 <ek...@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 <la...@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.
Re: Documentation Policy
Posted by Eugene Koifman <ek...@hortonworks.com>.
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 <la...@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.