forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: website documentation version
Date Wed, 03 Nov 2004 00:17:25 GMT
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.

No, not from the Tag but from the Branches.
We might need to make some crucial changes
after the release, to code and/or docs.

> > 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...

I was working with the assumption that we need to
separate out the global docs from the version-specific
docs. Of course this is complicated because we did not
plan this before the 0.6 release.

> > 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.


> > 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.

That was my main worry too. We could advise honest robots
via robots.txt file. Yes i would prefer that we limit it
to two sets, especially while we are still at 0.x versions.

> > 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 ...
>  > --------------------
> I was thinking of something different, but I'm still not sure... I have 
> rewritten this mail three times and understand that it's not so trivial 
> as it may seem, so I'll think out loud :-)

Me too. I spent about three hours on my version,
reaching logic dead-ends and constantly revising.
In the end i sent my best shot, knowing someone
else could help to tune it.

> The idea is to keep *all* the source docs in
> forrest/trunk/**, and checkout the site with
> a single svn co.

In that case i don't yet understand how to make
a release of Forrest which includes *only* the
relevant docs, but lets read on.

> ['svn://forrest' is used as a short version of
> --------------------
> Source SVN space
> --------------------
> svn://forrest
>            /trunk
>               /site (the only website)
> -----------------------------
> The published SVN space ...
> -----------------------------
> svn://forrest
>           /site
>              /trunk
>              /tags
>                /0.6
>                /0.7

Ah, i did not realise that we could have "trunk"
and "tags" and "branches" inside another level.

> The site trunk contains
> svn://
>    forrest/

Is there a typo here, missing "site/"?

>       trunk/  (generated from svn://forrest/trunk/site )
>        devdocs/ (contained in the generated trunk docs)
>       docs/ (copied from svn://forrest/site/tags/$latestversion/devdocs)
> When a release is made, the documentation is generated one last time and 
> checked in under the trunk.

This is a big assumption that we would never need
to make any further changes to old docs.

Could we get these assumptions clarified before we
discuss further. My whole proposal was based on my
assumption that we do need to cater for that need.

> Then a tag $latestversion is made, and svn://forrest/docs is copied from 
> svn://forrest/site/tags/$latestversion/devdocs.

Is that a typo above ... svn://forrest/docs

> --------------------
> The web space ...
> --------------------
> /www/
> ... the 'svn checkout' of svn://forrest/site/trunk/

We will need to spend time to get this whole
procedure correct and efficient. Unfortunately
this is holding up our publishing of the website
which is seriously confusing due to the sudden,
but necessary, SVN restructure.

David Crossley

View raw message