Lots of good points here; I'll see if I can address them in-line.
On 6/8/05, Steve Hanson <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED]
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 <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED]
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
