On Nov 1, 2005, at 8:27 PM, Rodent of Unusual Size wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
John Sisson wrote:
My main concern with the use of the Wiki for documentation is that
the
Wiki content isn't versioned to match Geronimo releases.
[snip]
An alternative is to develop the main documentation under svn control
(the Derby project does this), but that would mean updates would
have to
be submitted as patches. Derby's doco can be easily generated as
a PDF
with bookmarks etc, which is great for offline or printing.
Perhaps some mix would be good, such as a weekly checkin to
svn of any changes to the wiki. Of course, then there's
the issue of format compatibility. Do the wikis in use
provide for XML exports? If so, a little glue should be
able to automatically manage the conversion and checkin.
The major problems I see with that is that the who-changed-what
accountability is lost (unless a change to the wiki can
be included in the export as an XML entity that can be used
to identify the changer in svn), and that changes made
between checkpoints don't get recorded.
I've cranked my brain on this one for awhile as OpenEJB now uses
confluence for documentation rather than generating html from xml
stored in cvs as we did before.
XML importing and exporting is possible in confluence, as well as
html and pdf exports (no import for those, though). As a couple
releases ago, they also have the ability to have "listeners" or
something that you can set up to be executed when pages are changed,
added, removed, etc. So, the most aggressive approach I can think of
is that we could setup a listener that exports the entire page and
checks it into svn. Some less aggressive version of that is possible
too.
As far as versioning, the best i can think of would be to have a
Confluence Space per svn branch. So a GERONIMO-X space for each
release branch under geronimo/branches/. Using Tomcat as an example
as we don't have branches yet, that'd be something like TOMCAT-4,
TOMCAT-50 and TOMCAT-55. You could even start a new space by
exporting from the previous major version's space, creating a new
space, then importing to the new space. If you export aggressively,
you can start a new Space from what's in svn.
Anyway, I haven't solved the problem completely but thats a high
level dump of what's in my brain in regards to import/export, source
control, and versioning.
-David
