Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Subject: Re: website documentation version
From: David Crossley <crossley@apache.org>
To: dev@forrest.apache.org
In-Reply-To: <418818C3.3010607@brondsema.net>
References: <418724D2.5090706@brondsema.net> <cm795r$ihh$2@sea.gmane.org>
	 <41872AE2.1010407@brondsema.net> <1099378271.22790.64526.camel@ighp>
	 <cm7cp2$pcr$1@sea.gmane.org> <1099394407.22786.66331.camel@ighp>
	 <cm8285$gbl$1@sea.gmane.org>  <418818C3.3010607@brondsema.net>
Content-Type: text/plain
Organization: 
Message-Id: <1099453602.22786.73676.camel@ighp>
Mime-Version: 1.0
Date: 03 Nov 2004 14:46:56 +1100
Content-Transfer-Encoding: 7bit

Dave Brondsema wrote:
> Nicola Ken Barozzi wrote:
> > David Crossley wrote:
> > 
> >> Summary of the discussion so far. None of it is yet agreed.
> >> Please revise, if needed.
> >>
> >> The generated docs come from each separate release branch.
> > 
> > 
> >  From the 'tag' I suppose, as a tag denotes a release (it seems you mean 
> > the same thing). Plus one for the trunk.
> > 
> 
>  From a branch.  E.g., we need to fix the documentation at 
> http://forrest.apache.org/docs/your-project.html#images  We will do so 
> on the forrest_06 branch and the 0.6 webpages will be built from the 
> latest version of that branch.  If we do it from a tag, then we have to 
> wait until 0.6.1 is  released for that documentation change to get online.

That sounds like Dav* are on the same wavelength.
We will see what Nicola Ken reckons tomorrow.

> >> The top-level docs are in a separate repository for
> >> global things like the homepage, the example sites,
> >> the mailing list and other community-type info.
> > 
> > Hmmm... I want to also keep the top-level docs that were used for a 
> > release...
> 
> Which ones, and why?
> 
> >> Some docs (faq.* and build.*) would move into the
> >> version-specific at docs/faq.html etc.
> > 
> >> The branch docs have a warning banner.
> > 
> > With a like to the latest released docs.
> 
> The trunk docs would need a warning, too.  Users of the stable release 
> shouldn't be mislead by them.  But I don't want warnings everywhere, 
> just make it clear in the project title of those pages that it is Apache 
> Forrest 0.6, or Apache Forrest 0.7-dev

I agree, though i am not yet sure what is the best way
to make that very apparent yet not be too intrusive.

> >> Do we keep the old past release docs online forever?
> > 
> > 
> > Good question. IMHO we should keep the latest release docs plus the 
> > trunk docs. More than that can make indexing servers mix up the pages.
> > 
> >> The current ASF publishing is still done by storing the
> >> generated docs in SVN repositories. This might change later
> >> to use a staging server and rsync, or even a live server
> >> as Cocoon is now contemplating. Not yet.
> >>
> >> --------------------
> >> The web space ...
> >> --------------------
> > 
> > ...
> >  > --------------------
> >  > The SVN space ...
> >  > --------------------
> 
> Hrm, to publish each version's webpages, generated from the source in 
> the appropriate branch/trunk is not currently possible if it is all one 
> site.  If we do base the webpages from the documentation in branches & 
> trunk, it would probably be best to make each one a whole site.

I was coming around to that too. That is what Cocoon do.
They have a separate home page, which links to a whole site
for each separate version. But they do have separate top-level
content like contrib.html and mailing-lists.html etc. This
latter makes it very cumbersome, because a developer needs
to checkout the whole "generated docs" repository, including
every past release, just to work on the top-level docs.

So i like your idea, which i gather would use httpd
server redirect to serve the /dev/ and /stable/ docs.

> web space:
> -----------
> f.a.o/dev -> a whole forrest site (what we have now at f.a.o)
> f.a.o/0.6 -> a whole forrest site, from the 0.6 branch
> f.a.o/stable -> alias for 0.6
> f.a.o/index.html -> a quick intro paragraph, and links to the 
> subdirectories OR a redirect to /stable

This last item causes grief. Where is its source and how does
it get generated? So if we did the server redirect, then that
issue would be avoided.

> web files stored in svn:
> ---------
> same structure as they have in the web space, in svn://forrest/site

That sounds neat.

> documentation src files in svn:
> --------
> svn://forrest/trunk/src/documentation/content -> used to generate files 
> at f.a.o/dev

That is svn://forrest/trunk/site/content at the moment.

> svn://forrest/branches/forrest_06_branch/src/documentation/content  -> 
> used to generate files at f.a.o/0.6

Yes.

Another issue which we have each hinted at, is which
set of docs is the default? Is it the current dev trunk
or the release (0.6). The former is better for promoting
the capabilities of the project. The latter is better for
the users. I think the latter is best.

-- 
David Crossley