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:[email protected]
