You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@storm.apache.org by Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> on 2016/01/22 22:25:59 UTC
[DISCUSSION] Restructure Storm documentation
The new website is awesome.
Tt would be great to keep tabs on documentation for different versions of Storm and host those different versions on the site.
I don't care too much for having all the documentation in its own branch. I would suggest that each version branch of Storm keeps its own version of the docs -- or keeps any modifications to the docs, if not the entire collection, in order to keep the common parts in sync -- and that these docs get merged into the asf-site branch in their own version directory as part of the release process.
Please let me know what you think and I'll file Jira issues as necessary.-- Kyle
Re: [DISCUSSION] Restructure Storm documentation
Posted by Bobby Evans <ev...@yahoo-inc.com.INVALID>.
Just about every other project I have seen does it that way. There there is a common section and a subsection per release.
+1
- Bobby
On Friday, January 22, 2016 3:27 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> wrote:
The new website is awesome.
Tt would be great to keep tabs on documentation for different versions of Storm and host those different versions on the site.
I don't care too much for having all the documentation in its own branch. I would suggest that each version branch of Storm keeps its own version of the docs -- or keeps any modifications to the docs, if not the entire collection, in order to keep the common parts in sync -- and that these docs get merged into the asf-site branch in their own version directory as part of the release process.
Please let me know what you think and I'll file Jira issues as necessary.-- Kyle
Re: [DISCUSSION] Restructure Storm documentation
Posted by Abhishek Agarwal <ab...@gmail.com>.
+1 on having separate versions for 0.x 1.x and master. I can fork out the
documentation into three branches and try to fix the links for 0.x and 1.x.
master is changing at a rapid pace so it may be better to keep updating it
in continuous mode. The structure and process of generating and publishing
the documentation needs to be decided though.
On Sat, Feb 27, 2016 at 12:13 AM, Bobby Evans <ev...@yahoo-inc.com.invalid>
wrote:
> I agree there are some parts that are common, and should remain common.
> Then there are other parts that are very specific to a release and should
> be in a per release directory. Moving ASAP on this makes since to me.
> - Bobby
>
> On Friday, February 26, 2016 12:28 PM, Jungtaek Lim <ka...@gmail.com>
> wrote:
>
>
> Maybe we should adopt it ASAP, since links for source code seems to be
> already broken by two huge changes.
>
> Please refer https://issues.apache.org/jira/browse/STORM-1581 for more.
> (Thanks Abhishek)
>
> 1. moved package (which is already addressed to 1.x)
> 2. now porting clojure to java (only master)
>
> So, we should at least maintain three versions of docs, 0.x and 1.x, and
> 2.x (master).
>
> What do you think?
>
> Regards,
> Jungtaek Lim (HeartSaVioR)
>
> 2016년 2월 26일 (금) 오전 1:39, Abhishek Agarwal <ab...@gmail.com>님이 작성:
>
> > I have seen Apache Pig publishing a version specific documentation which
> is
> > generated through forrest.
> > e.g.
> > http://pig.apache.org/docs/r0.13.0/
> > http://pig.apache.org/docs/r0.14.0/
> >
> > Documentation is kept in the same branch in a separate folder. I haven't
> > looked in details but we can definitely borrow ideas from them.
> >
> >
> > On Tue, Jan 26, 2016 at 10:50 PM, Kyle Nusbaum <
> > knusbaum@yahoo-inc.com.invalid> wrote:
> >
> > > https://issues.apache.org/jira/browse/STORM-1502 -- Kyle
> > >
> > > On Sunday, January 24, 2016 4:29 PM, Jungtaek Lim <
> kabhwan@gmail.com
> > >
> > > wrote:
> > >
> > >
> > > +1 for having version specific docs.
> > >
> > > We move docs to asf-site branch, and now we have only one REST API doc.
> > for
> > > 1.0.0 and later versions.
> > >
> > > It would also great to describe available versions for each API, but
> just
> > > having whole copy may be easier.
> > > Same things may be applied to new features.
> > >
> > > - Jungtaek Lim (HeartSaVioR)
> > >
> > > 2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
> > >
> > > > +1 for having documentation for older releases on the website and
> > > > JavaDocs for each version, too.
> > > >
> > > > Btw: in the Flink project this process is automated completely. I am
> > not
> > > > sure exactly how, but could figure it out. However, the documentation
> > is
> > > > not part of the project website itself but hosted at ci.apache.org
> > > >
> > > > Having this automated, is very nice for people how are using the
> > current
> > > > Snapshot version, as the new docs get available very soon when
> > something
> > > > changes.
> > > >
> > > > -Matthias
> > > >
> > > >
> > > > On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > > > > At the very least, the Javadocs should be available by version.
> This
> > is
> > > > > something I used to do but looks like we forgot to keep doing that
> > > after
> > > > > the transition to Apache. Maintaining other docs (tutorials, etc.)
> by
> > > > > version is more difficult as those are rarely updated at the time
> of
> > > > > release.
> > > > >
> > > > > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> > > > wrote:
> > > > >
> > > > >> It doesn't have to be Taylor cutting releases. The only major
> > > > requirement
> > > > >> around that is that the PMC votes on the release.
> > > > >> - Bobby
> > > > >>
> > > > >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> > > > >> <kn...@yahoo-inc.com.INVALID> wrote:
> > > > >>
> > > > >>
> > > > >> Yep, That's precisely what I was thinking.
> > > > >>
> > > > >> I don't really see a problem with the process being manual. It
> won't
> > > be
> > > > >> *too* much work, and we do releases infrequently enough that I
> don't
> > > > see it
> > > > >> as a burden. A small helper script would probably be trivial to
> > write.
> > > > >>
> > > > >> Of course, Taylor is the one cutting the releases, so I'll defer
> to
> > > him
> > > > on
> > > > >> the automated/manual issue. -- Kyle
> > > > >>
> > > > >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> > > > >> ptgoetz@gmail.com> wrote:
> > > > >>
> > > > >>
> > > > >> I’m definitely open to improving the process such that we can
> have
> > > > >> version-specific documentation, and finding a way to automate
> > updating
> > > > the
> > > > >> asf-site branch during the release process. I’m also okay if that
> > > > process
> > > > >> is somewhat manual.
> > > > >>
> > > > >> I’ve thought about it a little but haven’t really come with a
> > process.
> > > > >>
> > > > >> Ideally we’d do something that would do a snapshot of the docs at
> > > > release
> > > > >> time and create a subdirectory in the asf-site website (e.g.
> > > > “1.0.0-docs”).
> > > > >>
> > > > >> I’m open to suggestions.
> > > > >>
> > > > >> -Taylor
> > > > >>
> > > > >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <
> knusbaum@yahoo-inc.com
> > > > .INVALID>
> > > > >> wrote:
> > > > >>>
> > > > >>> The new website is awesome.
> > > > >>>
> > > > >>> Tt would be great to keep tabs on documentation for different
> > > versions
> > > > >> of Storm and host those different versions on the site.
> > > > >>>
> > > > >>> I don't care too much for having all the documentation in its own
> > > > >> branch. I would suggest that each version branch of Storm keeps
> its
> > > own
> > > > >> version of the docs -- or keeps any modifications to the docs, if
> > not
> > > > the
> > > > >> entire collection, in order to keep the common parts in sync --
> and
> > > that
> > > > >> these docs get merged into the asf-site branch in their own
> version
> > > > >> directory as part of the release process.
> > > > >>> Please let me know what you think and I'll file Jira issues as
> > > > >> necessary.-- Kyle
> > > > >>
> > > > >>
> > > > >>
> > > > >>
> > > > >>
> > > > >>
> > > > >
> > > > >
> > > > >
> > > >
> > > >
> > >
> > >
> > >
> >
> >
> >
> > --
> > Regards,
> > Abhishek Agarwal
> >
>
>
>
--
Regards,
Abhishek Agarwal
Re: [DISCUSSION] Restructure Storm documentation
Posted by Bobby Evans <ev...@yahoo-inc.com.INVALID>.
I agree there are some parts that are common, and should remain common. Then there are other parts that are very specific to a release and should be in a per release directory. Moving ASAP on this makes since to me.
- Bobby
On Friday, February 26, 2016 12:28 PM, Jungtaek Lim <ka...@gmail.com> wrote:
Maybe we should adopt it ASAP, since links for source code seems to be
already broken by two huge changes.
Please refer https://issues.apache.org/jira/browse/STORM-1581 for more.
(Thanks Abhishek)
1. moved package (which is already addressed to 1.x)
2. now porting clojure to java (only master)
So, we should at least maintain three versions of docs, 0.x and 1.x, and
2.x (master).
What do you think?
Regards,
Jungtaek Lim (HeartSaVioR)
2016년 2월 26일 (금) 오전 1:39, Abhishek Agarwal <ab...@gmail.com>님이 작성:
> I have seen Apache Pig publishing a version specific documentation which is
> generated through forrest.
> e.g.
> http://pig.apache.org/docs/r0.13.0/
> http://pig.apache.org/docs/r0.14.0/
>
> Documentation is kept in the same branch in a separate folder. I haven't
> looked in details but we can definitely borrow ideas from them.
>
>
> On Tue, Jan 26, 2016 at 10:50 PM, Kyle Nusbaum <
> knusbaum@yahoo-inc.com.invalid> wrote:
>
> > https://issues.apache.org/jira/browse/STORM-1502 -- Kyle
> >
> > On Sunday, January 24, 2016 4:29 PM, Jungtaek Lim <kabhwan@gmail.com
> >
> > wrote:
> >
> >
> > +1 for having version specific docs.
> >
> > We move docs to asf-site branch, and now we have only one REST API doc.
> for
> > 1.0.0 and later versions.
> >
> > It would also great to describe available versions for each API, but just
> > having whole copy may be easier.
> > Same things may be applied to new features.
> >
> > - Jungtaek Lim (HeartSaVioR)
> >
> > 2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
> >
> > > +1 for having documentation for older releases on the website and
> > > JavaDocs for each version, too.
> > >
> > > Btw: in the Flink project this process is automated completely. I am
> not
> > > sure exactly how, but could figure it out. However, the documentation
> is
> > > not part of the project website itself but hosted at ci.apache.org
> > >
> > > Having this automated, is very nice for people how are using the
> current
> > > Snapshot version, as the new docs get available very soon when
> something
> > > changes.
> > >
> > > -Matthias
> > >
> > >
> > > On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > > > At the very least, the Javadocs should be available by version. This
> is
> > > > something I used to do but looks like we forgot to keep doing that
> > after
> > > > the transition to Apache. Maintaining other docs (tutorials, etc.) by
> > > > version is more difficult as those are rarely updated at the time of
> > > > release.
> > > >
> > > > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> > > wrote:
> > > >
> > > >> It doesn't have to be Taylor cutting releases. The only major
> > > requirement
> > > >> around that is that the PMC votes on the release.
> > > >> - Bobby
> > > >>
> > > >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> > > >> <kn...@yahoo-inc.com.INVALID> wrote:
> > > >>
> > > >>
> > > >> Yep, That's precisely what I was thinking.
> > > >>
> > > >> I don't really see a problem with the process being manual. It won't
> > be
> > > >> *too* much work, and we do releases infrequently enough that I don't
> > > see it
> > > >> as a burden. A small helper script would probably be trivial to
> write.
> > > >>
> > > >> Of course, Taylor is the one cutting the releases, so I'll defer to
> > him
> > > on
> > > >> the automated/manual issue. -- Kyle
> > > >>
> > > >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> > > >> ptgoetz@gmail.com> wrote:
> > > >>
> > > >>
> > > >> I’m definitely open to improving the process such that we can have
> > > >> version-specific documentation, and finding a way to automate
> updating
> > > the
> > > >> asf-site branch during the release process. I’m also okay if that
> > > process
> > > >> is somewhat manual.
> > > >>
> > > >> I’ve thought about it a little but haven’t really come with a
> process.
> > > >>
> > > >> Ideally we’d do something that would do a snapshot of the docs at
> > > release
> > > >> time and create a subdirectory in the asf-site website (e.g.
> > > “1.0.0-docs”).
> > > >>
> > > >> I’m open to suggestions.
> > > >>
> > > >> -Taylor
> > > >>
> > > >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <knusbaum@yahoo-inc.com
> > > .INVALID>
> > > >> wrote:
> > > >>>
> > > >>> The new website is awesome.
> > > >>>
> > > >>> Tt would be great to keep tabs on documentation for different
> > versions
> > > >> of Storm and host those different versions on the site.
> > > >>>
> > > >>> I don't care too much for having all the documentation in its own
> > > >> branch. I would suggest that each version branch of Storm keeps its
> > own
> > > >> version of the docs -- or keeps any modifications to the docs, if
> not
> > > the
> > > >> entire collection, in order to keep the common parts in sync -- and
> > that
> > > >> these docs get merged into the asf-site branch in their own version
> > > >> directory as part of the release process.
> > > >>> Please let me know what you think and I'll file Jira issues as
> > > >> necessary.-- Kyle
> > > >>
> > > >>
> > > >>
> > > >>
> > > >>
> > > >>
> > > >
> > > >
> > > >
> > >
> > >
> >
> >
> >
>
>
>
> --
> Regards,
> Abhishek Agarwal
>
Re: [DISCUSSION] Restructure Storm documentation
Posted by Jungtaek Lim <ka...@gmail.com>.
Maybe we should adopt it ASAP, since links for source code seems to be
already broken by two huge changes.
Please refer https://issues.apache.org/jira/browse/STORM-1581 for more.
(Thanks Abhishek)
1. moved package (which is already addressed to 1.x)
2. now porting clojure to java (only master)
So, we should at least maintain three versions of docs, 0.x and 1.x, and
2.x (master).
What do you think?
Regards,
Jungtaek Lim (HeartSaVioR)
2016년 2월 26일 (금) 오전 1:39, Abhishek Agarwal <ab...@gmail.com>님이 작성:
> I have seen Apache Pig publishing a version specific documentation which is
> generated through forrest.
> e.g.
> http://pig.apache.org/docs/r0.13.0/
> http://pig.apache.org/docs/r0.14.0/
>
> Documentation is kept in the same branch in a separate folder. I haven't
> looked in details but we can definitely borrow ideas from them.
>
>
> On Tue, Jan 26, 2016 at 10:50 PM, Kyle Nusbaum <
> knusbaum@yahoo-inc.com.invalid> wrote:
>
> > https://issues.apache.org/jira/browse/STORM-1502 -- Kyle
> >
> > On Sunday, January 24, 2016 4:29 PM, Jungtaek Lim <kabhwan@gmail.com
> >
> > wrote:
> >
> >
> > +1 for having version specific docs.
> >
> > We move docs to asf-site branch, and now we have only one REST API doc.
> for
> > 1.0.0 and later versions.
> >
> > It would also great to describe available versions for each API, but just
> > having whole copy may be easier.
> > Same things may be applied to new features.
> >
> > - Jungtaek Lim (HeartSaVioR)
> >
> > 2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
> >
> > > +1 for having documentation for older releases on the website and
> > > JavaDocs for each version, too.
> > >
> > > Btw: in the Flink project this process is automated completely. I am
> not
> > > sure exactly how, but could figure it out. However, the documentation
> is
> > > not part of the project website itself but hosted at ci.apache.org
> > >
> > > Having this automated, is very nice for people how are using the
> current
> > > Snapshot version, as the new docs get available very soon when
> something
> > > changes.
> > >
> > > -Matthias
> > >
> > >
> > > On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > > > At the very least, the Javadocs should be available by version. This
> is
> > > > something I used to do but looks like we forgot to keep doing that
> > after
> > > > the transition to Apache. Maintaining other docs (tutorials, etc.) by
> > > > version is more difficult as those are rarely updated at the time of
> > > > release.
> > > >
> > > > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> > > wrote:
> > > >
> > > >> It doesn't have to be Taylor cutting releases. The only major
> > > requirement
> > > >> around that is that the PMC votes on the release.
> > > >> - Bobby
> > > >>
> > > >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> > > >> <kn...@yahoo-inc.com.INVALID> wrote:
> > > >>
> > > >>
> > > >> Yep, That's precisely what I was thinking.
> > > >>
> > > >> I don't really see a problem with the process being manual. It won't
> > be
> > > >> *too* much work, and we do releases infrequently enough that I don't
> > > see it
> > > >> as a burden. A small helper script would probably be trivial to
> write.
> > > >>
> > > >> Of course, Taylor is the one cutting the releases, so I'll defer to
> > him
> > > on
> > > >> the automated/manual issue. -- Kyle
> > > >>
> > > >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> > > >> ptgoetz@gmail.com> wrote:
> > > >>
> > > >>
> > > >> I’m definitely open to improving the process such that we can have
> > > >> version-specific documentation, and finding a way to automate
> updating
> > > the
> > > >> asf-site branch during the release process. I’m also okay if that
> > > process
> > > >> is somewhat manual.
> > > >>
> > > >> I’ve thought about it a little but haven’t really come with a
> process.
> > > >>
> > > >> Ideally we’d do something that would do a snapshot of the docs at
> > > release
> > > >> time and create a subdirectory in the asf-site website (e.g.
> > > “1.0.0-docs”).
> > > >>
> > > >> I’m open to suggestions.
> > > >>
> > > >> -Taylor
> > > >>
> > > >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <knusbaum@yahoo-inc.com
> > > .INVALID>
> > > >> wrote:
> > > >>>
> > > >>> The new website is awesome.
> > > >>>
> > > >>> Tt would be great to keep tabs on documentation for different
> > versions
> > > >> of Storm and host those different versions on the site.
> > > >>>
> > > >>> I don't care too much for having all the documentation in its own
> > > >> branch. I would suggest that each version branch of Storm keeps its
> > own
> > > >> version of the docs -- or keeps any modifications to the docs, if
> not
> > > the
> > > >> entire collection, in order to keep the common parts in sync -- and
> > that
> > > >> these docs get merged into the asf-site branch in their own version
> > > >> directory as part of the release process.
> > > >>> Please let me know what you think and I'll file Jira issues as
> > > >> necessary.-- Kyle
> > > >>
> > > >>
> > > >>
> > > >>
> > > >>
> > > >>
> > > >
> > > >
> > > >
> > >
> > >
> >
> >
> >
>
>
>
> --
> Regards,
> Abhishek Agarwal
>
Re: [DISCUSSION] Restructure Storm documentation
Posted by Abhishek Agarwal <ab...@gmail.com>.
I have seen Apache Pig publishing a version specific documentation which is
generated through forrest.
e.g.
http://pig.apache.org/docs/r0.13.0/
http://pig.apache.org/docs/r0.14.0/
Documentation is kept in the same branch in a separate folder. I haven't
looked in details but we can definitely borrow ideas from them.
On Tue, Jan 26, 2016 at 10:50 PM, Kyle Nusbaum <
knusbaum@yahoo-inc.com.invalid> wrote:
> https://issues.apache.org/jira/browse/STORM-1502 -- Kyle
>
> On Sunday, January 24, 2016 4:29 PM, Jungtaek Lim <ka...@gmail.com>
> wrote:
>
>
> +1 for having version specific docs.
>
> We move docs to asf-site branch, and now we have only one REST API doc. for
> 1.0.0 and later versions.
>
> It would also great to describe available versions for each API, but just
> having whole copy may be easier.
> Same things may be applied to new features.
>
> - Jungtaek Lim (HeartSaVioR)
>
> 2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
>
> > +1 for having documentation for older releases on the website and
> > JavaDocs for each version, too.
> >
> > Btw: in the Flink project this process is automated completely. I am not
> > sure exactly how, but could figure it out. However, the documentation is
> > not part of the project website itself but hosted at ci.apache.org
> >
> > Having this automated, is very nice for people how are using the current
> > Snapshot version, as the new docs get available very soon when something
> > changes.
> >
> > -Matthias
> >
> >
> > On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > > At the very least, the Javadocs should be available by version. This is
> > > something I used to do but looks like we forgot to keep doing that
> after
> > > the transition to Apache. Maintaining other docs (tutorials, etc.) by
> > > version is more difficult as those are rarely updated at the time of
> > > release.
> > >
> > > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> > wrote:
> > >
> > >> It doesn't have to be Taylor cutting releases. The only major
> > requirement
> > >> around that is that the PMC votes on the release.
> > >> - Bobby
> > >>
> > >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> > >> <kn...@yahoo-inc.com.INVALID> wrote:
> > >>
> > >>
> > >> Yep, That's precisely what I was thinking.
> > >>
> > >> I don't really see a problem with the process being manual. It won't
> be
> > >> *too* much work, and we do releases infrequently enough that I don't
> > see it
> > >> as a burden. A small helper script would probably be trivial to write.
> > >>
> > >> Of course, Taylor is the one cutting the releases, so I'll defer to
> him
> > on
> > >> the automated/manual issue. -- Kyle
> > >>
> > >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> > >> ptgoetz@gmail.com> wrote:
> > >>
> > >>
> > >> I’m definitely open to improving the process such that we can have
> > >> version-specific documentation, and finding a way to automate updating
> > the
> > >> asf-site branch during the release process. I’m also okay if that
> > process
> > >> is somewhat manual.
> > >>
> > >> I’ve thought about it a little but haven’t really come with a process.
> > >>
> > >> Ideally we’d do something that would do a snapshot of the docs at
> > release
> > >> time and create a subdirectory in the asf-site website (e.g.
> > “1.0.0-docs”).
> > >>
> > >> I’m open to suggestions.
> > >>
> > >> -Taylor
> > >>
> > >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <knusbaum@yahoo-inc.com
> > .INVALID>
> > >> wrote:
> > >>>
> > >>> The new website is awesome.
> > >>>
> > >>> Tt would be great to keep tabs on documentation for different
> versions
> > >> of Storm and host those different versions on the site.
> > >>>
> > >>> I don't care too much for having all the documentation in its own
> > >> branch. I would suggest that each version branch of Storm keeps its
> own
> > >> version of the docs -- or keeps any modifications to the docs, if not
> > the
> > >> entire collection, in order to keep the common parts in sync -- and
> that
> > >> these docs get merged into the asf-site branch in their own version
> > >> directory as part of the release process.
> > >>> Please let me know what you think and I'll file Jira issues as
> > >> necessary.-- Kyle
> > >>
> > >>
> > >>
> > >>
> > >>
> > >>
> > >
> > >
> > >
> >
> >
>
>
>
--
Regards,
Abhishek Agarwal
Re: [DISCUSSION] Restructure Storm documentation
Posted by Kyle Nusbaum <kn...@yahoo-inc.com.INVALID>.
https://issues.apache.org/jira/browse/STORM-1502 -- Kyle
On Sunday, January 24, 2016 4:29 PM, Jungtaek Lim <ka...@gmail.com> wrote:
+1 for having version specific docs.
We move docs to asf-site branch, and now we have only one REST API doc. for
1.0.0 and later versions.
It would also great to describe available versions for each API, but just
having whole copy may be easier.
Same things may be applied to new features.
- Jungtaek Lim (HeartSaVioR)
2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
> +1 for having documentation for older releases on the website and
> JavaDocs for each version, too.
>
> Btw: in the Flink project this process is automated completely. I am not
> sure exactly how, but could figure it out. However, the documentation is
> not part of the project website itself but hosted at ci.apache.org
>
> Having this automated, is very nice for people how are using the current
> Snapshot version, as the new docs get available very soon when something
> changes.
>
> -Matthias
>
>
> On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > At the very least, the Javadocs should be available by version. This is
> > something I used to do but looks like we forgot to keep doing that after
> > the transition to Apache. Maintaining other docs (tutorials, etc.) by
> > version is more difficult as those are rarely updated at the time of
> > release.
> >
> > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> wrote:
> >
> >> It doesn't have to be Taylor cutting releases. The only major
> requirement
> >> around that is that the PMC votes on the release.
> >> - Bobby
> >>
> >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> >> <kn...@yahoo-inc.com.INVALID> wrote:
> >>
> >>
> >> Yep, That's precisely what I was thinking.
> >>
> >> I don't really see a problem with the process being manual. It won't be
> >> *too* much work, and we do releases infrequently enough that I don't
> see it
> >> as a burden. A small helper script would probably be trivial to write.
> >>
> >> Of course, Taylor is the one cutting the releases, so I'll defer to him
> on
> >> the automated/manual issue. -- Kyle
> >>
> >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> >> ptgoetz@gmail.com> wrote:
> >>
> >>
> >> I’m definitely open to improving the process such that we can have
> >> version-specific documentation, and finding a way to automate updating
> the
> >> asf-site branch during the release process. I’m also okay if that
> process
> >> is somewhat manual.
> >>
> >> I’ve thought about it a little but haven’t really come with a process.
> >>
> >> Ideally we’d do something that would do a snapshot of the docs at
> release
> >> time and create a subdirectory in the asf-site website (e.g.
> “1.0.0-docs”).
> >>
> >> I’m open to suggestions.
> >>
> >> -Taylor
> >>
> >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <knusbaum@yahoo-inc.com
> .INVALID>
> >> wrote:
> >>>
> >>> The new website is awesome.
> >>>
> >>> Tt would be great to keep tabs on documentation for different versions
> >> of Storm and host those different versions on the site.
> >>>
> >>> I don't care too much for having all the documentation in its own
> >> branch. I would suggest that each version branch of Storm keeps its own
> >> version of the docs -- or keeps any modifications to the docs, if not
> the
> >> entire collection, in order to keep the common parts in sync -- and that
> >> these docs get merged into the asf-site branch in their own version
> >> directory as part of the release process.
> >>> Please let me know what you think and I'll file Jira issues as
> >> necessary.-- Kyle
> >>
> >>
> >>
> >>
> >>
> >>
> >
> >
> >
>
>
Re: [DISCUSSION] Restructure Storm documentation
Posted by Jungtaek Lim <ka...@gmail.com>.
+1 for having version specific docs.
We move docs to asf-site branch, and now we have only one REST API doc. for
1.0.0 and later versions.
It would also great to describe available versions for each API, but just
having whole copy may be easier.
Same things may be applied to new features.
- Jungtaek Lim (HeartSaVioR)
2016년 1월 25일 (월) 오전 12:19, Matthias J. Sax <mj...@apache.org>님이 작성:
> +1 for having documentation for older releases on the website and
> JavaDocs for each version, too.
>
> Btw: in the Flink project this process is automated completely. I am not
> sure exactly how, but could figure it out. However, the documentation is
> not part of the project website itself but hosted at ci.apache.org
>
> Having this automated, is very nice for people how are using the current
> Snapshot version, as the new docs get available very soon when something
> changes.
>
> -Matthias
>
>
> On 01/22/2016 11:59 PM, Nathan Marz wrote:
> > At the very least, the Javadocs should be available by version. This is
> > something I used to do but looks like we forgot to keep doing that after
> > the transition to Apache. Maintaining other docs (tutorials, etc.) by
> > version is more difficult as those are rarely updated at the time of
> > release.
> >
> > On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com>
> wrote:
> >
> >> It doesn't have to be Taylor cutting releases. The only major
> requirement
> >> around that is that the PMC votes on the release.
> >> - Bobby
> >>
> >> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> >> <kn...@yahoo-inc.com.INVALID> wrote:
> >>
> >>
> >> Yep, That's precisely what I was thinking.
> >>
> >> I don't really see a problem with the process being manual. It won't be
> >> *too* much work, and we do releases infrequently enough that I don't
> see it
> >> as a burden. A small helper script would probably be trivial to write.
> >>
> >> Of course, Taylor is the one cutting the releases, so I'll defer to him
> on
> >> the automated/manual issue. -- Kyle
> >>
> >> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> >> ptgoetz@gmail.com> wrote:
> >>
> >>
> >> I’m definitely open to improving the process such that we can have
> >> version-specific documentation, and finding a way to automate updating
> the
> >> asf-site branch during the release process. I’m also okay if that
> process
> >> is somewhat manual.
> >>
> >> I’ve thought about it a little but haven’t really come with a process.
> >>
> >> Ideally we’d do something that would do a snapshot of the docs at
> release
> >> time and create a subdirectory in the asf-site website (e.g.
> “1.0.0-docs”).
> >>
> >> I’m open to suggestions.
> >>
> >> -Taylor
> >>
> >>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <knusbaum@yahoo-inc.com
> .INVALID>
> >> wrote:
> >>>
> >>> The new website is awesome.
> >>>
> >>> Tt would be great to keep tabs on documentation for different versions
> >> of Storm and host those different versions on the site.
> >>>
> >>> I don't care too much for having all the documentation in its own
> >> branch. I would suggest that each version branch of Storm keeps its own
> >> version of the docs -- or keeps any modifications to the docs, if not
> the
> >> entire collection, in order to keep the common parts in sync -- and that
> >> these docs get merged into the asf-site branch in their own version
> >> directory as part of the release process.
> >>> Please let me know what you think and I'll file Jira issues as
> >> necessary.-- Kyle
> >>
> >>
> >>
> >>
> >>
> >>
> >
> >
> >
>
>
Re: [DISCUSSION] Restructure Storm documentation
Posted by "Matthias J. Sax" <mj...@apache.org>.
+1 for having documentation for older releases on the website and
JavaDocs for each version, too.
Btw: in the Flink project this process is automated completely. I am not
sure exactly how, but could figure it out. However, the documentation is
not part of the project website itself but hosted at ci.apache.org
Having this automated, is very nice for people how are using the current
Snapshot version, as the new docs get available very soon when something
changes.
-Matthias
On 01/22/2016 11:59 PM, Nathan Marz wrote:
> At the very least, the Javadocs should be available by version. This is
> something I used to do but looks like we forgot to keep doing that after
> the transition to Apache. Maintaining other docs (tutorials, etc.) by
> version is more difficult as those are rarely updated at the time of
> release.
>
> On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com> wrote:
>
>> It doesn't have to be Taylor cutting releases. The only major requirement
>> around that is that the PMC votes on the release.
>> - Bobby
>>
>> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
>> <kn...@yahoo-inc.com.INVALID> wrote:
>>
>>
>> Yep, That's precisely what I was thinking.
>>
>> I don't really see a problem with the process being manual. It won't be
>> *too* much work, and we do releases infrequently enough that I don't see it
>> as a burden. A small helper script would probably be trivial to write.
>>
>> Of course, Taylor is the one cutting the releases, so I'll defer to him on
>> the automated/manual issue. -- Kyle
>>
>> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
>> ptgoetz@gmail.com> wrote:
>>
>>
>> I’m definitely open to improving the process such that we can have
>> version-specific documentation, and finding a way to automate updating the
>> asf-site branch during the release process. I’m also okay if that process
>> is somewhat manual.
>>
>> I’ve thought about it a little but haven’t really come with a process.
>>
>> Ideally we’d do something that would do a snapshot of the docs at release
>> time and create a subdirectory in the asf-site website (e.g. “1.0.0-docs”).
>>
>> I’m open to suggestions.
>>
>> -Taylor
>>
>>> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID>
>> wrote:
>>>
>>> The new website is awesome.
>>>
>>> Tt would be great to keep tabs on documentation for different versions
>> of Storm and host those different versions on the site.
>>>
>>> I don't care too much for having all the documentation in its own
>> branch. I would suggest that each version branch of Storm keeps its own
>> version of the docs -- or keeps any modifications to the docs, if not the
>> entire collection, in order to keep the common parts in sync -- and that
>> these docs get merged into the asf-site branch in their own version
>> directory as part of the release process.
>>> Please let me know what you think and I'll file Jira issues as
>> necessary.-- Kyle
>>
>>
>>
>>
>>
>>
>
>
>
Re: [DISCUSSION] Restructure Storm documentation
Posted by Nathan Marz <na...@nathanmarz.com>.
At the very least, the Javadocs should be available by version. This is
something I used to do but looks like we forgot to keep doing that after
the transition to Apache. Maintaining other docs (tutorials, etc.) by
version is more difficult as those are rarely updated at the time of
release.
On Fri, Jan 22, 2016 at 2:01 PM, Bobby Evans <ev...@yahoo-inc.com> wrote:
> It doesn't have to be Taylor cutting releases. The only major requirement
> around that is that the PMC votes on the release.
> - Bobby
>
> On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum
> <kn...@yahoo-inc.com.INVALID> wrote:
>
>
> Yep, That's precisely what I was thinking.
>
> I don't really see a problem with the process being manual. It won't be
> *too* much work, and we do releases infrequently enough that I don't see it
> as a burden. A small helper script would probably be trivial to write.
>
> Of course, Taylor is the one cutting the releases, so I'll defer to him on
> the automated/manual issue. -- Kyle
>
> On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <
> ptgoetz@gmail.com> wrote:
>
>
> I’m definitely open to improving the process such that we can have
> version-specific documentation, and finding a way to automate updating the
> asf-site branch during the release process. I’m also okay if that process
> is somewhat manual.
>
> I’ve thought about it a little but haven’t really come with a process.
>
> Ideally we’d do something that would do a snapshot of the docs at release
> time and create a subdirectory in the asf-site website (e.g. “1.0.0-docs”).
>
> I’m open to suggestions.
>
> -Taylor
>
> > On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID>
> wrote:
> >
> > The new website is awesome.
> >
> > Tt would be great to keep tabs on documentation for different versions
> of Storm and host those different versions on the site.
> >
> > I don't care too much for having all the documentation in its own
> branch. I would suggest that each version branch of Storm keeps its own
> version of the docs -- or keeps any modifications to the docs, if not the
> entire collection, in order to keep the common parts in sync -- and that
> these docs get merged into the asf-site branch in their own version
> directory as part of the release process.
> > Please let me know what you think and I'll file Jira issues as
> necessary.-- Kyle
>
>
>
>
>
>
--
Twitter: @nathanmarz
http://nathanmarz.com
Re: [DISCUSSION] Restructure Storm documentation
Posted by Bobby Evans <ev...@yahoo-inc.com>.
It doesn't have to be Taylor cutting releases. The only major requirement around that is that the PMC votes on the release.
- Bobby
On Friday, January 22, 2016 3:48 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> wrote:
Yep, That's precisely what I was thinking.
I don't really see a problem with the process being manual. It won't be *too* much work, and we do releases infrequently enough that I don't see it as a burden. A small helper script would probably be trivial to write.
Of course, Taylor is the one cutting the releases, so I'll defer to him on the automated/manual issue. -- Kyle
On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <pt...@gmail.com> wrote:
I’m definitely open to improving the process such that we can have version-specific documentation, and finding a way to automate updating the asf-site branch during the release process. I’m also okay if that process is somewhat manual.
I’ve thought about it a little but haven’t really come with a process.
Ideally we’d do something that would do a snapshot of the docs at release time and create a subdirectory in the asf-site website (e.g. “1.0.0-docs”).
I’m open to suggestions.
-Taylor
> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> wrote:
>
> The new website is awesome.
>
> Tt would be great to keep tabs on documentation for different versions of Storm and host those different versions on the site.
>
> I don't care too much for having all the documentation in its own branch. I would suggest that each version branch of Storm keeps its own version of the docs -- or keeps any modifications to the docs, if not the entire collection, in order to keep the common parts in sync -- and that these docs get merged into the asf-site branch in their own version directory as part of the release process.
> Please let me know what you think and I'll file Jira issues as necessary.-- Kyle
Re: [DISCUSSION] Restructure Storm documentation
Posted by Kyle Nusbaum <kn...@yahoo-inc.com.INVALID>.
Yep, That's precisely what I was thinking.
I don't really see a problem with the process being manual. It won't be *too* much work, and we do releases infrequently enough that I don't see it as a burden. A small helper script would probably be trivial to write.
Of course, Taylor is the one cutting the releases, so I'll defer to him on the automated/manual issue. -- Kyle
On Friday, January 22, 2016 3:45 PM, P. Taylor Goetz <pt...@gmail.com> wrote:
I’m definitely open to improving the process such that we can have version-specific documentation, and finding a way to automate updating the asf-site branch during the release process. I’m also okay if that process is somewhat manual.
I’ve thought about it a little but haven’t really come with a process.
Ideally we’d do something that would do a snapshot of the docs at release time and create a subdirectory in the asf-site website (e.g. “1.0.0-docs”).
I’m open to suggestions.
-Taylor
> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> wrote:
>
> The new website is awesome.
>
> Tt would be great to keep tabs on documentation for different versions of Storm and host those different versions on the site.
>
> I don't care too much for having all the documentation in its own branch. I would suggest that each version branch of Storm keeps its own version of the docs -- or keeps any modifications to the docs, if not the entire collection, in order to keep the common parts in sync -- and that these docs get merged into the asf-site branch in their own version directory as part of the release process.
> Please let me know what you think and I'll file Jira issues as necessary.-- Kyle
Re: [DISCUSSION] Restructure Storm documentation
Posted by "P. Taylor Goetz" <pt...@gmail.com>.
I’m definitely open to improving the process such that we can have version-specific documentation, and finding a way to automate updating the asf-site branch during the release process. I’m also okay if that process is somewhat manual.
I’ve thought about it a little but haven’t really come with a process.
Ideally we’d do something that would do a snapshot of the docs at release time and create a subdirectory in the asf-site website (e.g. “1.0.0-docs”).
I’m open to suggestions.
-Taylor
> On Jan 22, 2016, at 4:25 PM, Kyle Nusbaum <kn...@yahoo-inc.com.INVALID> wrote:
>
> The new website is awesome.
>
> Tt would be great to keep tabs on documentation for different versions of Storm and host those different versions on the site.
>
> I don't care too much for having all the documentation in its own branch. I would suggest that each version branch of Storm keeps its own version of the docs -- or keeps any modifications to the docs, if not the entire collection, in order to keep the common parts in sync -- and that these docs get merged into the asf-site branch in their own version directory as part of the release process.
> Please let me know what you think and I'll file Jira issues as necessary.-- Kyle