You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geode.apache.org by Roman Shaposhnik <ro...@shaposhnik.org> on 2015/05/26 17:46:11 UTC
Bringing geode website into the project
Hi!
I've been sitting on this for some time, but finally
managed to get a moment to actually prototype it.
After trying a dozen different tools (including JRuby
version of Jekyll) I settled on JBake (http://jbake.org)
and would like to propose it for now as our website
management tool.
The nice thing about JBake is that it allows mixing
markdown and asciidoc markups so we can gradually
transition our content from one to the other.
Currently this is an MVP that simply allows us to
manage the web site in a natural way by leveraging
the following gradle commands:
jbake -- for preparing the content
jbakeRun -- for previewing the content on localhost
jbakePublish -- for publishing into asf-site branch
Anyway, please review and let me know WDYT. To
make it easier for reviewers I've created a PR as
well. You can see it linked to the JIRA:
https://issues.apache.org/jira/browse/GEODE-21
Thanks,
Roman.
Re: Bringing geode website into the project
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Tue, May 26, 2015 at 3:47 PM, Dan Smith <ds...@pivotal.io> wrote:
> +1
>
> My reading of the code in the PR is a little different than what William
> just said. Based on the PR it looks like the source code for the site will
> be in a subdirectory called gemfire-site on the develop branch, and the
> generated output will get pushed to that asf-site orphaned branch. Then
> some magic serves that branch up as http://geode.incubator.apache.org
> <http://geode.incubator.apache.orgThat>. Roman, can you clarify?
That's exactly right: gemfire-site folder will host 'static' portion
of our website
content. However, with time, I see it as an assembly point for anything
that we would need to publish via http. Things like JavaDocs, Reports
of any kind, etc. Here's a good example of what we've done with
another project I'm involved in:
http://giraph.apache.org/project-reports.html
All of that, however, will get published via a magic asf-site branch that
is nothing more but a way of exposing static html that we intend to
be served up from http://geode.incubator.apache.org
Thanks,
Roman.
Re: Bringing geode website into the project
Posted by William Markito <wm...@pivotal.io>.
You're correct Dan, my bad. I meant gemfire-site instead of asf-site in my
comment.
On Tue, May 26, 2015 at 3:47 PM, Dan Smith <ds...@pivotal.io> wrote:
> +1
>
> My reading of the code in the PR is a little different than what William
> just said. Based on the PR it looks like the source code for the site will
> be in a subdirectory called gemfire-site on the develop branch, and the
> generated output will get pushed to that asf-site orphaned branch. Then
> some magic serves that branch up as http://geode.incubator.apache.org
> <http://geode.incubator.apache.orgThat>. Roman, can you clarify?
>
> -Dan
>
>
>
> On Tue, May 26, 2015 at 10:02 AM, Luke Shannon <ls...@pivotal.io>
> wrote:
>
> > +2 for JBake
> >
> > On Tue, May 26, 2015 at 12:44 PM, William Markito <wm...@pivotal.io>
> > wrote:
> >
> > > Actually the website source is already under ASF git right ?
> > >
> > >
> > >
> >
> https://git-wip-us.apache.org/repos/asf?p=incubator-geode.git;a=shortlog;h=refs/heads/asf-site
> > >
> > > +1 for JBake
> > >
> > > My understanding is that the gradle tasks would pull from that repo,
> > build
> > > and update geode.incubator.apache.org with the html files.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > > On Tue, May 26, 2015 at 9:04 AM, Anthony Baker <ab...@pivotal.io>
> > wrote:
> > >
> > > > Currently the website source is hosted at
> > > > https://github.com/project-geode/docs/tree/gh-pages correct?
> > > >
> > > > Once we have JBake in place where will the site source be hosted? In
> > the
> > > > ASF repo on an orphan branch or on /develop?
> > > >
> > > > How does geode.incubator.apache.org get updated from asf-site?
> > > >
> > > > Anthony
> > > >
> > > >
> > > > > On May 26, 2015, at 8:46 AM, Roman Shaposhnik <
> roman@shaposhnik.org>
> > > > wrote:
> > > > >
> > > > > Hi!
> > > > >
> > > > > I've been sitting on this for some time, but finally
> > > > > managed to get a moment to actually prototype it.
> > > > >
> > > > > After trying a dozen different tools (including JRuby
> > > > > version of Jekyll) I settled on JBake (http://jbake.org)
> > > > > and would like to propose it for now as our website
> > > > > management tool.
> > > > >
> > > > > The nice thing about JBake is that it allows mixing
> > > > > markdown and asciidoc markups so we can gradually
> > > > > transition our content from one to the other.
> > > > >
> > > > > Currently this is an MVP that simply allows us to
> > > > > manage the web site in a natural way by leveraging
> > > > > the following gradle commands:
> > > > > jbake -- for preparing the content
> > > > > jbakeRun -- for previewing the content on localhost
> > > > > jbakePublish -- for publishing into asf-site branch
> > > > >
> > > > > Anyway, please review and let me know WDYT. To
> > > > > make it easier for reviewers I've created a PR as
> > > > > well. You can see it linked to the JIRA:
> > > > > https://issues.apache.org/jira/browse/GEODE-21
> > > > >
> > > > > Thanks,
> > > > > Roman.
> > > >
> > > >
> > >
> > >
> > > --
> > >
> > > William Markito Oliveira
> > >
> > > -- For questions about Apache Geode, please write to
> > > *dev@geode.incubator.apache.org
> > > <de...@geode.incubator.apache.org>*
> > >
> >
> >
> >
> > --
> > Luke Shannon | Sr. Field Engineer - Toronto | Pivotal
> > -------------------------------------------------------------------------
> > Mobile:416-571-9495
> > Join the Toronto Pivotal Usergroup:
> > http://www.meetup.com/Toronto-Pivotal-User-Group/
> >
>
--
William Markito Oliveira
-- For questions about Apache Geode, please write to
*dev@geode.incubator.apache.org
<de...@geode.incubator.apache.org>*
Re: Bringing geode website into the project
Posted by Dan Smith <ds...@pivotal.io>.
+1
My reading of the code in the PR is a little different than what William
just said. Based on the PR it looks like the source code for the site will
be in a subdirectory called gemfire-site on the develop branch, and the
generated output will get pushed to that asf-site orphaned branch. Then
some magic serves that branch up as http://geode.incubator.apache.org
<http://geode.incubator.apache.orgThat>. Roman, can you clarify?
-Dan
On Tue, May 26, 2015 at 10:02 AM, Luke Shannon <ls...@pivotal.io> wrote:
> +2 for JBake
>
> On Tue, May 26, 2015 at 12:44 PM, William Markito <wm...@pivotal.io>
> wrote:
>
> > Actually the website source is already under ASF git right ?
> >
> >
> >
> https://git-wip-us.apache.org/repos/asf?p=incubator-geode.git;a=shortlog;h=refs/heads/asf-site
> >
> > +1 for JBake
> >
> > My understanding is that the gradle tasks would pull from that repo,
> build
> > and update geode.incubator.apache.org with the html files.
> >
> >
> >
> >
> >
> >
> >
> >
> > On Tue, May 26, 2015 at 9:04 AM, Anthony Baker <ab...@pivotal.io>
> wrote:
> >
> > > Currently the website source is hosted at
> > > https://github.com/project-geode/docs/tree/gh-pages correct?
> > >
> > > Once we have JBake in place where will the site source be hosted? In
> the
> > > ASF repo on an orphan branch or on /develop?
> > >
> > > How does geode.incubator.apache.org get updated from asf-site?
> > >
> > > Anthony
> > >
> > >
> > > > On May 26, 2015, at 8:46 AM, Roman Shaposhnik <ro...@shaposhnik.org>
> > > wrote:
> > > >
> > > > Hi!
> > > >
> > > > I've been sitting on this for some time, but finally
> > > > managed to get a moment to actually prototype it.
> > > >
> > > > After trying a dozen different tools (including JRuby
> > > > version of Jekyll) I settled on JBake (http://jbake.org)
> > > > and would like to propose it for now as our website
> > > > management tool.
> > > >
> > > > The nice thing about JBake is that it allows mixing
> > > > markdown and asciidoc markups so we can gradually
> > > > transition our content from one to the other.
> > > >
> > > > Currently this is an MVP that simply allows us to
> > > > manage the web site in a natural way by leveraging
> > > > the following gradle commands:
> > > > jbake -- for preparing the content
> > > > jbakeRun -- for previewing the content on localhost
> > > > jbakePublish -- for publishing into asf-site branch
> > > >
> > > > Anyway, please review and let me know WDYT. To
> > > > make it easier for reviewers I've created a PR as
> > > > well. You can see it linked to the JIRA:
> > > > https://issues.apache.org/jira/browse/GEODE-21
> > > >
> > > > Thanks,
> > > > Roman.
> > >
> > >
> >
> >
> > --
> >
> > William Markito Oliveira
> >
> > -- For questions about Apache Geode, please write to
> > *dev@geode.incubator.apache.org
> > <de...@geode.incubator.apache.org>*
> >
>
>
>
> --
> Luke Shannon | Sr. Field Engineer - Toronto | Pivotal
> -------------------------------------------------------------------------
> Mobile:416-571-9495
> Join the Toronto Pivotal Usergroup:
> http://www.meetup.com/Toronto-Pivotal-User-Group/
>
Re: Bringing geode website into the project
Posted by Luke Shannon <ls...@pivotal.io>.
+2 for JBake
On Tue, May 26, 2015 at 12:44 PM, William Markito <wm...@pivotal.io>
wrote:
> Actually the website source is already under ASF git right ?
>
>
> https://git-wip-us.apache.org/repos/asf?p=incubator-geode.git;a=shortlog;h=refs/heads/asf-site
>
> +1 for JBake
>
> My understanding is that the gradle tasks would pull from that repo, build
> and update geode.incubator.apache.org with the html files.
>
>
>
>
>
>
>
>
> On Tue, May 26, 2015 at 9:04 AM, Anthony Baker <ab...@pivotal.io> wrote:
>
> > Currently the website source is hosted at
> > https://github.com/project-geode/docs/tree/gh-pages correct?
> >
> > Once we have JBake in place where will the site source be hosted? In the
> > ASF repo on an orphan branch or on /develop?
> >
> > How does geode.incubator.apache.org get updated from asf-site?
> >
> > Anthony
> >
> >
> > > On May 26, 2015, at 8:46 AM, Roman Shaposhnik <ro...@shaposhnik.org>
> > wrote:
> > >
> > > Hi!
> > >
> > > I've been sitting on this for some time, but finally
> > > managed to get a moment to actually prototype it.
> > >
> > > After trying a dozen different tools (including JRuby
> > > version of Jekyll) I settled on JBake (http://jbake.org)
> > > and would like to propose it for now as our website
> > > management tool.
> > >
> > > The nice thing about JBake is that it allows mixing
> > > markdown and asciidoc markups so we can gradually
> > > transition our content from one to the other.
> > >
> > > Currently this is an MVP that simply allows us to
> > > manage the web site in a natural way by leveraging
> > > the following gradle commands:
> > > jbake -- for preparing the content
> > > jbakeRun -- for previewing the content on localhost
> > > jbakePublish -- for publishing into asf-site branch
> > >
> > > Anyway, please review and let me know WDYT. To
> > > make it easier for reviewers I've created a PR as
> > > well. You can see it linked to the JIRA:
> > > https://issues.apache.org/jira/browse/GEODE-21
> > >
> > > Thanks,
> > > Roman.
> >
> >
>
>
> --
>
> William Markito Oliveira
>
> -- For questions about Apache Geode, please write to
> *dev@geode.incubator.apache.org
> <de...@geode.incubator.apache.org>*
>
--
Luke Shannon | Sr. Field Engineer - Toronto | Pivotal
-------------------------------------------------------------------------
Mobile:416-571-9495
Join the Toronto Pivotal Usergroup:
http://www.meetup.com/Toronto-Pivotal-User-Group/
Re: Bringing geode website into the project
Posted by William Markito <wm...@pivotal.io>.
Actually the website source is already under ASF git right ?
https://git-wip-us.apache.org/repos/asf?p=incubator-geode.git;a=shortlog;h=refs/heads/asf-site
+1 for JBake
My understanding is that the gradle tasks would pull from that repo, build
and update geode.incubator.apache.org with the html files.
On Tue, May 26, 2015 at 9:04 AM, Anthony Baker <ab...@pivotal.io> wrote:
> Currently the website source is hosted at
> https://github.com/project-geode/docs/tree/gh-pages correct?
>
> Once we have JBake in place where will the site source be hosted? In the
> ASF repo on an orphan branch or on /develop?
>
> How does geode.incubator.apache.org get updated from asf-site?
>
> Anthony
>
>
> > On May 26, 2015, at 8:46 AM, Roman Shaposhnik <ro...@shaposhnik.org>
> wrote:
> >
> > Hi!
> >
> > I've been sitting on this for some time, but finally
> > managed to get a moment to actually prototype it.
> >
> > After trying a dozen different tools (including JRuby
> > version of Jekyll) I settled on JBake (http://jbake.org)
> > and would like to propose it for now as our website
> > management tool.
> >
> > The nice thing about JBake is that it allows mixing
> > markdown and asciidoc markups so we can gradually
> > transition our content from one to the other.
> >
> > Currently this is an MVP that simply allows us to
> > manage the web site in a natural way by leveraging
> > the following gradle commands:
> > jbake -- for preparing the content
> > jbakeRun -- for previewing the content on localhost
> > jbakePublish -- for publishing into asf-site branch
> >
> > Anyway, please review and let me know WDYT. To
> > make it easier for reviewers I've created a PR as
> > well. You can see it linked to the JIRA:
> > https://issues.apache.org/jira/browse/GEODE-21
> >
> > Thanks,
> > Roman.
>
>
--
William Markito Oliveira
-- For questions about Apache Geode, please write to
*dev@geode.incubator.apache.org
<de...@geode.incubator.apache.org>*
Re: Bringing geode website into the project
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Thu, May 28, 2015 at 4:14 AM, Justin Erenkrantz
<ju...@erenkrantz.com> wrote:
> On Wed, May 27, 2015 at 9:04 PM, Roman Shaposhnik <ro...@shaposhnik.org> wrote:
>> On Wed, May 27, 2015 at 8:53 AM, Anthony Baker <ab...@pivotal.io> wrote:
>>> Aren’t we limited to a single repo during incubation?
>>
>> Pretty much.
>
> Meh. If it's the right thing to do to have multiple git repositories,
> then we should just do that.
[...snip...]
> So, let's not have the SCM dictate making a horrible mess out of the
> source repository.
The real question I have is not even mechanics of the repos, but rather
mechanics of releases. IMHO the things that need to evolved and be
released together -- gotta live in the same repo.
I am pretty convinced that website and things like Javadocs fall into
that category. Things like plugins and demos and extensions -- don't know.
For poddling though (read high velocity of changes) I'd rather err
on the side of putting more things in the common repo since it
makes it way easier to make sure that changes don't break them.
> I haven't seen a discussion yet what the versioning and lifecycle of
> Geode should be. What's the current thinking there?
>
> If there will be multiple concurrently supported versions, then there
> should be corresponding published release documentations. Some
> examples:
>
> httpd:
> http://httpd.apache.org/docs/2.4/
> http://httpd.apache.org/docs/2.2/
> http://httpd.apache.org/docs/trunk/
>
> Ceph:
> http://ceph.com/docs/ (defaults to master, notice the selector at bottom right)
>
> If we go that route, then I don't think that it'll make sense to have
> all of the historical documentation versions exploded in a single
> folder. It should be some type of branching scheme...so, probably
> sitting in the source tree for each branch/tag.
And that's another reason why I like docs in the same release tarball
(and part of the same build process, etc.) it makes a job of a downstream
consumer (Bigtop, Linux distros, etc.) *way* easier.
Thanks,
Roman.
Re: Bringing geode website into the project
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
On Wed, May 27, 2015 at 9:04 PM, Roman Shaposhnik <ro...@shaposhnik.org> wrote:
> On Wed, May 27, 2015 at 8:53 AM, Anthony Baker <ab...@pivotal.io> wrote:
>> Aren’t we limited to a single repo during incubation?
>
> Pretty much.
Meh. If it's the right thing to do to have multiple git repositories,
then we should just do that.
With Subversion, it's fairly trivial to create subdirs just for docs,
sites, etc. that are parallel to the source tree. Git actively
encourages having very small repositories.
So, let's not have the SCM dictate making a horrible mess out of the
source repository.
(IOW, this would be a non-issue with Subversion with a "single"
repository, but is extremely painful with git.)
>> Within that repo we need to manage:
>>
>> - Source for geode components
>> - Website source
>> - Documentation source
>>
>> What are your thoughts for bringing in the documentation source?
>> Stashing it in a subproject (‘geode-docs’) on the /develop branch?
>> How does it get pushed out for online hosting?
>
> I guess a different way to ask this would be: what are the expectations
> for maintaining and releasing those docs? If the docs need to correspond
> to each release of Geode then maintaining them as part of the same repo
> is the only practical way of actually releasing them (remember ASF releases are
> the tarballs not what's your git repo). In that case I'd suggest geode-docs
> folder on /develop branch.
I haven't seen a discussion yet what the versioning and lifecycle of
Geode should be. What's the current thinking there?
If there will be multiple concurrently supported versions, then there
should be corresponding published release documentations. Some
examples:
httpd:
http://httpd.apache.org/docs/2.4/
http://httpd.apache.org/docs/2.2/
http://httpd.apache.org/docs/trunk/
Ceph:
http://ceph.com/docs/ (defaults to master, notice the selector at bottom right)
If we go that route, then I don't think that it'll make sense to have
all of the historical documentation versions exploded in a single
folder. It should be some type of branching scheme...so, probably
sitting in the source tree for each branch/tag.
My $.02. -- justin
Re: Bringing geode website into the project
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Wed, May 27, 2015 at 8:53 AM, Anthony Baker <ab...@pivotal.io> wrote:
> Aren’t we limited to a single repo during incubation?
Pretty much.
> Within that repo we need to manage:
>
> - Source for geode components
> - Website source
> - Documentation source
>
> What are your thoughts for bringing in the documentation source?
> Stashing it in a subproject (‘geode-docs’) on the /develop branch?
> How does it get pushed out for online hosting?
I guess a different way to ask this would be: what are the expectations
for maintaining and releasing those docs? If the docs need to correspond
to each release of Geode then maintaining them as part of the same repo
is the only practical way of actually releasing them (remember ASF releases are
the tarballs not what's your git repo). In that case I'd suggest geode-docs
folder on /develop branch.
That still doesn't answer the question of how to publish them (since they
can't be served as static html pages) but we can tackle that aspect of
it in parallel (I can start a thread with ASF INFRA).
If that makes sense -- I'll follow up with a JIRA shortly.
Thanks,
Roman.
Re: Bringing geode website into the project
Posted by Anthony Baker <ab...@pivotal.io>.
Aren’t we limited to a single repo during incubation? Within that repo we need to manage:
- Source for geode components
- Website source
- Documentation source
What are your thoughts for bringing in the documentation source? Stashing it in a subproject (‘geode-docs’) on the /develop branch? How does it get pushed out for online hosting?
Anthony
> On May 26, 2015, at 6:21 PM, Roman Shaposhnik <ro...@shaposhnik.org> wrote:
>
> At this point, I'm of two minds on the docs issue: on one hand having
> them hosted in the same repo as the rest of the project will simplify
> things. On the other hand the way they are managed makes them
> sort of incongruent with how we manage everything else in the project.
Re: Bringing geode website into the project
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Tue, May 26, 2015 at 9:04 AM, Anthony Baker <ab...@pivotal.io> wrote:
> Currently the website source is hosted at https://github.com/project-geode/docs/tree/gh-pages correct?
Yup. And the idea is to migrate away from that repo. Once we're done
with the site migration the docs themselves will be the next ones.
At this point, I'm of two minds on the docs issue: on one hand having
them hosted in the same repo as the rest of the project will simplify
things. On the other hand the way they are managed makes them
sort of incongruent with how we manage everything else in the project.
And on top of that -- they can't be served as static HTML pages.
> Once we have JBake in place where will the site source be hosted?
> In the ASF repo on an orphan branch or on /develop?
Well, it'll be part of the project.
> How does geode.incubator.apache.org get updated from asf-site?
What gets served via http is 100% idential to the state of the branch.
Thanks,
Roman.
Re: Bringing geode website into the project
Posted by Anthony Baker <ab...@pivotal.io>.
Currently the website source is hosted at https://github.com/project-geode/docs/tree/gh-pages correct?
Once we have JBake in place where will the site source be hosted? In the ASF repo on an orphan branch or on /develop?
How does geode.incubator.apache.org get updated from asf-site?
Anthony
> On May 26, 2015, at 8:46 AM, Roman Shaposhnik <ro...@shaposhnik.org> wrote:
>
> Hi!
>
> I've been sitting on this for some time, but finally
> managed to get a moment to actually prototype it.
>
> After trying a dozen different tools (including JRuby
> version of Jekyll) I settled on JBake (http://jbake.org)
> and would like to propose it for now as our website
> management tool.
>
> The nice thing about JBake is that it allows mixing
> markdown and asciidoc markups so we can gradually
> transition our content from one to the other.
>
> Currently this is an MVP that simply allows us to
> manage the web site in a natural way by leveraging
> the following gradle commands:
> jbake -- for preparing the content
> jbakeRun -- for previewing the content on localhost
> jbakePublish -- for publishing into asf-site branch
>
> Anyway, please review and let me know WDYT. To
> make it easier for reviewers I've created a PR as
> well. You can see it linked to the JIRA:
> https://issues.apache.org/jira/browse/GEODE-21
>
> Thanks,
> Roman.