Mailing-List: contact beehive-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Beehive Developers" <beehive-dev@incubator.apache.org>
Received-SPF: pass (hermes.apache.org: domain of ekoneil@gmail.com designates
 64.233.184.206 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:reply-to:to:subject:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references;
        b=MR84/YTuvN+2HAZ5+cTu4t+uPlHJKYZ1Xlcg/GE94wRVtbmhyycG1uFyDgNVX5txEYtj1L7NDku7sFMDfMuHkj5M+fZ9MvJYASpd6nLGM4MIEls4wQUJNgP5AvU1M4KiOfnSlAO1sa89cv0qYKaPyxBKR9TMshxWElaVhutQbAU=
Message-ID: <e9ac83540506111703533ec18a@mail.gmail.com>
Date: Sat, 11 Jun 2005 18:03:34 -0600
From: Eddie ONeil <ekoneil@gmail.com>
Reply-To: Eddie ONeil <ekoneil@gmail.com>
To: Beehive Developers <beehive-dev@incubator.apache.org>
Subject: Re: updating the beehive web site -- a two pronged approach
In-Reply-To: <42AB6B2B.4080408@apache.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
References: <4C2F1577F2EF2840A9AE9EC61860C88101DF2DEA@usseex01.amer.bea.com>
	 <e9ac835405060819505905ceff@mail.gmail.com>
	 <42AB6B2B.4080408@apache.org>

  Yeah, as far as I've been concerned -- they are separate issues and
(1) is clearly more important and has much greater immediate impact.

  (2) was a suggested fix for the longer-term problem of multiple
versions of the documentation.

  If it's easier to discuss them separately, I'll spin (2) out into
it's own discussion.

  :)

Eddie


On 6/11/05, Rich Feit <rich@apache.org> wrote:
> No inline comments from me; just two quick ones:
>=20
>     - I wholeheartedly agree with Eddie's comments about getting the
> site into svn.  Anyone have any other feedback on this?
>=20
>     - While I agree with separating release-agnostic and
> release-specific doc, it sounds like there are some technical
> issues/questions to work through.  Could we separate the two "prongs" in
> this thread so one isn't dependent on the other?  It just seems like the
> amount of discussion between the two could get overwhelming, and it
> would be great to act on at least one relatively soon.  :)
>=20
> Rich
>=20
> Eddie ONeil wrote:
>=20
> >  Lots of good points here; I'll see if I can address them in-line.
> >
> >
> >On 6/8/05, Steve Hanson <steveh@bea.com> wrote:
> >
> >
> >>Let me preface this by saying that updating the live site is currently =
a medium-sized pain in the neck that will become a large-size pain when mul=
tiple versions of Beehive arrive.
> >>
> >>
> >
> >Agreed.  Thus changing how this works.  :)
> >
> >
> >
> >>More concerns about (1):
> >>------------------------
> >>
> >>That said, I don't think we should checkin Javadoc-generated HTML to th=
e tree at any level.  One reason is just pure principle: it just seems wron=
g to checkin something that gets generated from a build file.  There are al=
so practical reasons:  I agree that devs generally shouldn't have to sync t=
o beehive/site.  But people will still sync to it inadvertently, and get ma=
d about it, and break their local SVN tree trying to stop the sync midstrea=
m, etc.
> >>
> >>
> >
> >Generally, I agree about avoiding checking in generated files, and in
> >the end, this still might not work, but it seems worth having a
> >discussion about this to see what bright ideas we can come up with.
> >
> >I spent Sunday working with the Incubator website while updating the
> >Beehive status page, and the generated site is checked into SVN.  It
> >was a *joy* to be able to generate the site locally, make sure
> >everything worked locally, commit the changes to the site-publish
> >directory, and "svn update" on the server.  Worked out fabulously.
> >
> >Thus, I was (am) hoping we can do the same thing for the Beehive documen=
tation.
> >
> >I actually believe that lots of devs (esp committers) will sync
> >beehive/site because it needs updating.  As far as inadvertently
> >syncing part of the tree, we're already there with branches for three
> >releases and private sandboxes.  So, that doesn't seem like a limiting
> >factor.
> >
> >:)
> >
> >
> >
> >>Moreover: there are just *a lot* of HTML files to manage under SVN, whi=
ch is a pain in itself.  When I was managing them for the v1-alpha release,=
 I ran into these sorts of problems: A dev adds a new method to some class.=
  I want to get the new method posted that day, so I run Javadoc.  But each=
 generated HTML file is time-stamped, so SVN sees a change in every HTML fi=
le in the set.  The result is a submit that takes 1/2 an hour.  You might s=
ay: "Well couldn't you just checkin the one HTML class topic that has chang=
ed?"  Not really, because adding a new method to a class makes a whole seri=
es of small, medium and large sized changes across multiple HTML pages, cha=
nges which aren't easy to predict and selectively identify for a checkin.
> >>
> >>
> >
> >My proposal here wouldn't be that devs update the Javadoc -- that's
> >something that is done when the nightlies run, is totally scripted,
> >and happens (often) at 2 AM.  The publish/ directory isn't something
> >that would usually be updated incrementally -- it's something that's
> >updated in bulk, and 99% of the time that process is automated.
> >
> >
> >
> >
> >>More concerns about (2):
> >>------------------------
> >>
> >>Just to make sure I understand proposal (2), let me restate it:
> >>
> >>   We should make a distinction between the release-dependent and relea=
se-independent docs.
> >>   Release-dependent docs include the majority of topics like the user =
guides, tutorials, etc.
> >>   Release-independent docs include the more static parts of the site, =
like the download page,
> >>   mailing-list page, etc.
> >>   The release-independent docs should be moved up a level to beehive/s=
ite, where Forrest will
> >>   treat them like a relatively static site template.
> >>
> >>That's my restatement of proposal (2).  If I've misunderstood it, stop =
now, and set me straight.
> >>
> >>If I have restated (2) correctly, I don't think that Forrest can handle=
 it.  Even if we can find a way for Forrest to handle and build against XML=
 pages in two disparate directories, there are still other problems.
> >>
> >>
> >>
> >
> >Hm.  Guess the question I'd ask here is this -- why is this a problem
> >for Forrest?  We need to move the doc infrastructure to a place where
> >this is possible (note, these are hypothetical release numbers):
> >
> >beehive/
> >  branches/
> >    v1/
> >      v1.0/
> >      v1.1/
> >      v1.2/
> >
> >which will result in a website that looks like:
> >
> >  beehive/
> >    <core-site>
> >    releases/
> >      v1.0/
> >      v1.1/
> >      v1.2/
> >    nightly/
> >
> >where the v1.0, v1.1, v1.2 docs are generated from the branches/
> >directory and nightly/ comes from trunk/.  Currently, we don't seem to
> >have a clean way to do this because the entire site is re-generated
> >from the current release.  So, things like the downloads, mailinglist,
> >and other version agnostic content comes from the site generated by
> >the most recent release.  If a committer wants to add a "news" bullet,
> >post v1/m1, they've got to re-generate the site from the branch.
> >
> >Seems that it'd be easier to make a change to the Forrest XML file,
> >rebuild the version-agnostic content and update a single file...
> >
> >
> >
> >>It is just difficult, in principle, to make a division between non-vers=
ioned parts of a doc set and versioned parts.  For example, take the downlo=
ad page.  If we make it a non-versioned part of the doc set, really a commo=
n, templated element to any doc set, then, how do we handle regeneration of=
 an older version of the doc?  Suppose we need to regenerate version 1: Do =
we included the download page, with its reference/link to version 2?
> >>
> >>
> >
> >To me the download page isn't something that needs to branch with the
> >source tree -- it would already be versioned in SVN and if we needed
> >an older version of the doc, we'd just sync back to an older SVN
> >version fo the file.
> >
> >Is there any way to assemble documentation generated by multiple
> >Forrest runs?  Seems that if we're ever to support multiple versions
> >of the documentation that we'll need to be able to do this.  If it's
> >possible, we can just go low-tech and checkin the version-agnostic
> >parts of the site and generate the doc for each release and copy it as
> >we do today.
> >
> >
> >
> >
> >
> >
> >>All that said, I don't really have any brilliant ideas right now to dea=
l with the pain that is coming our way as the versions of the docs start to=
 proliferate.
> >>
> >>Maybe we need a script on the live site server that can run the doc tar=
gets and post the results?  That way you won't need to run processes on two=
 different machines.
> >>
> >>-steveh.
> >>
> >>
> >>-----Original Message-----
> >>From: Eddie ONeil [mailto:ekoneil@gmail.com]
> >>Sent: Wednesday, June 08, 2005 2:22 PM
> >>To: Beehive Developers
> >>Subject: Re: updating the beehive web site -- a two pronged approach
> >>
> >>
> >>Steve--
> >>
> >>  Comments in line.
> >>
> >>Eddie
> >>
> >>On 6/8/05, Steve Hanson <steveh@bea.com> wrote:
> >>
> >>
> >>>Hi all:
> >>>
> >>>Concerns and questions concerning (1):
> >>>
> >>>A system very similar to proposal (1) was in place for the v1-alpha re=
lease.
> >>>One complaint about it at the time was that Javadoc-generated HTML pag=
es were being checked in to SVN.  I am not sure how the current proposal (1=
) avoids this drawback.
> >>>
> >>>
> >>You're correct -- the Javadoc is checked into SVN, but it's done so in
> >>a location like:
> >>
> >>  beehive/
> >>    site/
> >>      publish/
> >>        ...
> >>
> >>which keeps it entirely out of the beehive/trunk directory.  As I
> >>recall, keeping the Javadoc in trunk/ was the issue as we were always
> >>sync-ing updates.
> >>
> >>The difference here is that it's up at the beehive/site/... level
> >>which devs don't usually need to sync.
> >>
> >>
> >>
> >>>One question: Are we going to be checking in different doc sets for ea=
ch released version of Beehive, so that the tree would look (something) lik=
e?:
> >>>
> >>>beehive
> >>>  site
> >>>    archives
> >>>      v1
> >>>      v2
> >>>    current
> >>>      v3
> >>>
> >>>
> >>>
> >>In the long run, yes.  This would make it *significantly* easier to
> >>keep the alpha, beta, m1, etc docs on the site and allow them to be
> >>updateable independently.
> >>
> >>
> >>
> >>>Concerns about (2):
> >>>
> >>>This proposal sounds like it would break Forrest.  Forrest is looking =
for one directory that contains the XML source files: I doubt it can handle=
 a disparate set of directories.  Runnng Forrest mulitple times and slappin=
g the genered HTML together afterwards won't work either, because Forrest n=
eeds to do link checking and build a single TOC.
> >>>
> >>>
> >>>
> >>Actually, I don't think it breaks Forrest if to generate the entire
> >>doc-kit, Forrest runs multiple times.  For example, to update the
> >>documentation for a nightly, we'd do something like this:
> >>
> >>- build a nightly distribution from trunk/
> >>- copy the documentation from trunk/build/dist/... up to
> >>site/publish/docs/nightly/...
> >>- svn commit the site/publish/docs/nightly directory
> >>- svn checkout on the live-site to refresh the web site
> >>
> >>Make sense?  If I'm nuts, let me know.  Just trying to lower the bar
> >>for updating the site and for allowing us to keep multiple copies of
> >>the doc on the site at once.
> >>
> >>
> >>
> >>
> >>>Craig R. McClanahan: I know that you have talked about these very issu=
es in Struts...do you have any insights here?
> >>>
> >>>-steve h.
> >>>
> >>>
> >>>
> >>>
> >>>-----Original Message-----
> >>>From: Eddie ONeil [mailto:ekoneil@gmail.com]
> >>>Sent: Tuesday, June 07, 2005 8:05 PM
> >>>To: Beehive Developers
> >>>Subject: updating the beehive web site -- a two pronged approach
> >>>
> >>>
> >>>All--
> >>>
> >>>  After having worked on the Beehive website some in the last couple
> >>>of days, I've got a couple of suggestions for how we can make this
> >>>process significantly easier.  The approach has two parts...  The
> >>>first is the most (immediately) important.
> >>>
> >>>1) check the generated website into beehive/site in a read-only part
> >>>of SVN.  This would allow committers to generate the website, check it
> >>>into SVN, and then check it out on the server.  This process avoids
> >>>the generation and "scp" of a .zip file to the server and then the
> >>>"ssh" to crack the .zip file.  To update the site, just run "svn
> >>>update" on the live site.  This also makes it easier to roll back
> >>>after a failed change.
> >>>
> >>>2) the next step would be to decouple the release-independent content
> >>>of the site from the release-dependent documentation.  This would move
> >>>things like the links to the mailinglists, downloads page, news page,
> >>>etc out of trunk/ and up a level so that it's versioned independently
> >>>of the versions of Beehive.  This is checked into something like:
> >>>
> >>>beehive/
> >>>  site/
> >>>    author/ -- location for the content in the tree
> >>>    publish/ -- location of the generated site
> >>>
> >>>Then, the release documentation can be generated, copied up to
> >>>publish/, checked into the tree, and "svn update"ed on the live site.
> >>>
> >>>Step (1) is something we can do now and would make updating the site
> >>>quite easy.  Step (2) is something we can do longer term but would
> >>>decouple the release documentation from the more static website.
> >>>
> >>>  Thoughts?
> >>>
> >>>Eddie
> >>>
> >>>
> >>>
> >
> >
> >
>=20
>