beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eddie ONeil <ekon...@gmail.com>
Subject Re: updating the beehive web site -- a two pronged approach
Date Sun, 12 Jun 2005 00:03:34 GMT
  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:
> 
>     - I wholeheartedly agree with Eddie's comments about getting the
> site into svn.  Anyone have any other feedback on this?
> 
>     - 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.  :)
> 
> Rich
> 
> Eddie ONeil wrote:
> 
> >  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 multiple 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 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.
> >>
> >>
> >
> >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 documentation.
> >
> >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, 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.
> >>
> >>
> >
> >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 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.
> >>
> >>
> >>
> >
> >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-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?
> >>
> >>
> >
> >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 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