beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steve Hanson" <ste...@bea.com>
Subject RE: updating the beehive web site -- a two pronged approach
Date Wed, 08 Jun 2005 23:32:53 GMT
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 multiple versions of Beehive arrive.

More concerns about (1):
------------------------

That said, I don't think we should checkin Javadoc-generated HTML to the tree at any level.
 One reason is just pure principle: it just seems wrong to checkin something that gets generated
from a build file.  There are also practical reasons:  I agree that devs generally shouldn't
have to sync to beehive/site.  But people will still sync to it inadvertently, and get mad
about it, and break their local SVN tree trying to stop the sync midstream, etc.  

Moreover: there are just *a lot* of HTML files to manage under SVN, which 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
file in the set.  The result is a submit that takes 1/2 an hour.  You might say: "Well couldn't
you just checkin the one HTML class topic that has changed?"  Not really, because adding a
new method to a class makes a whole series of small, medium and large sized changes across
multiple HTML pages, changes which aren't easy to predict and selectively identify for a checkin.


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 release-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/site, 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.

It is just difficult, in principle, to make a division between non-versioned parts of a doc
set and versioned parts.  For example, take the download page.  If we make it a non-versioned
part of the doc set, really a common, 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?

All that said, I don't really have any brilliant ideas right now to deal 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 targets 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 release.
> One complaint about it at the time was that Javadoc-generated HTML pages 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 each released version
of Beehive, so that the tree would look (something) like?:
> 
> 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 slapping the genered HTML together afterwards won't work
either, because Forrest needs 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 issues 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
>

Mime
View raw message