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 <[EMAIL PROTECTED]> 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 <[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 > >>> > >>> > >>> > > > > > > > >
