beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Feit <richf...@gmail.com>
Subject Re: updating the beehive web site -- a two pronged approach
Date Tue, 14 Jun 2005 03:33:50 GMT
So... +1 from me for #1 ("check the generated website into 
beehive/site").  Anyone else have any comment on that one?

Eddie ONeil wrote:

>  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