On Jan 3, 2007, at 3:24 AM, Mark Brouwer wrote:
Craig L Russell wrote:
It's ok, but unless you changed the typos in both docs and xdocs,
the changes in docs will be overwritten by the next build of the
same page from the xdocs sources. The xdocs and docs content
appear to be in sync as of now...
Is there a particular reason why the generated site must be checked in
as well, besides how it works right now?
The rationale is that
1) you can do QA - you can always be sure that the bits that are
being published are the same bits that you checked with your browser
locally on your system.
2) In the event of loss o a machine, it's easy to simply pull the
site out of SVN and deploy, w/o having to get all the tooling in
place to regen (if you are ASF infra, for example)
It also makes it easy to add the site to any distributions of the
software (which I think is useful, especially if you get the docs on
the website)
I haven't a full understanding of modifying the content of the
site, but
if the xdocs are the sources to be converted in the content to be
served
by the web server to me it seems that only the source should be in the
repository as this seems to be asking for troubles. People
modifying the
wrong content, forgetting to check in newly generated pages, etc.
Maybe I'm worrying about nothing, but no doubt I will be told ;-)
It's really not a problem in practice. The only time it bites is
when you forget to add new pages, but that can happen for source too
just as easily.
Usual work pattern is :
$ svn update
<make modifications>
$ ant
<check mods>
$ svn commit
with an optional $svn add xxxxx if there are new things to add and
to be sure, follow with $svn stat to make sure you got everything.
I would expect to see the process here 1) discuss idea on the
list 2) open
JIRA ticket 3) add patch to ticket and subsequently refer to the
ticket
number in discussion.
Agreed, but for rather trivial things such as "correct typos in ...",
"clean formatting ..." I hope we can skip 1) and if it is really
trivial and can be done as part of another piece of work even 2)
Yes, I agree. If the project is going to use JIRA, this process
should be changed to specify how to use JIRA.
+1 for JIRA
A good discussion might be whether to use JIRA for site updates.
For trivial updates like you mentioned, it's probably more trouble
than it's worth.
+1 for JIRA for site updates, in fact I hope to have the same
process as
you suggested with the same exceptions I mentioned before. As long as
the site is a separate component in JIRA.
By the way, the process to update the web site is documented at
river/site/README.txt. Terse but well worth reading.
Next thing for me to do.
--
Mark
