On Tue, 2010-04-27 at 10:47 -0400, Rafael Schloming wrote: > Jonathan Robie wrote: > > I think we're converging on using svnpubsub to maintain documentation. > > > > We need to determine our directory structure. Any of these structures > > make sense to me. In all cases, qpid.apache.org includes Rajith's > > index.html and associated .css, etc., as well as the DocBook generated > > files. It would contain links to the download directory and the Wiki, > > but not include them. > > > > Here are some possible directory structures: > > > > 1. Make the web site a subdirectory of doc > > > > doc/src <-- XML source files > > doc/build <-- the build directory > > doc/qpid.apache.org <-- the Apache web site, starting with index.html, > > and including all documentation. > > > > > > 2. Make the web site a parallel directory to doc > > > > qpd/cpp > > qpid/doc > > qpid/qpid.apache.org > > > > I suppose it would also be logically possible to have the web site be on > > a separate svn branch, or even in a separate svn repository. > > > > I'm inclined to go with #2. Does anyone else have strong feelings on this? > > I think the web site really needs to be a distinct repo from the one we > use for code for a few reasons. > > First, it is very confusing and generally considered horribly bad > practice to mix source code and generated artifacts in the same repo. > This confuses build systems to no end since most build systems are > predicated upon the concept that they are the only thing that ever > modifies the output files. However if the output files are in svn, then > an svn update can cause an older file to appear newer than the input > resulting in very confusing and broken behavior where the build system > doesn't actually build everything that needs to be built. In this > circumstance this could very easily lead to a broken and partially > updated web site, especially when developers follow the best practice of > doing an svn update prior to building in order to ensure they are > working from fresh sources. > > Secondly, I don't want to be exposed to getting multi-megabyte diffs > everytime someone updates the web site. > > Thirdly, the doc source should be part of the source release (i.e. an > svn export), however the generated web site should *not*. > > And finally, I think that if we're using svnpubsub for the web site, we > may well want to have other portions of the site in svn, not just the > docs, so the web site repo should be organized to reflect this.
+1 - I agree on all counts. This might actually be a place where the "stupid" arrangement of our repo to have a superfluous "qpid" directory might help: Currently the repo structure is actually: qpid + trunk +qpid + branches +<branchname> + qpid So we could use the existing structure and put the checked in docs in parallel like: ....qpid/trunk/qpid.apache.org But actually I'd prefer a simpler solution - why not just make it completely separate viz: http://svn.apache.org/repos/asf/qpid/qpid.apache.org Either of these places will avoid the usual dev check out from picking up the checked in web source. If infrastructure are happy to give us a completely separate repo then this might be better as it would be easier to give it its own access control. Andrew --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:dev-subscr...@qpid.apache.org