qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Stitcher <astitc...@redhat.com>
Subject Re: Proposed directory structure for web site
Date Tue, 27 Apr 2010 15:04:43 GMT
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-subscribe@qpid.apache.org


Mime
View raw message