forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Brondsema <d...@brondsema.net>
Subject Re: website documentation version
Date Wed, 03 Nov 2004 18:19:56 GMT
Quoting Nicola Ken Barozzi <nicolaken@apache.org>:

> David Crossley 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.
> > 
> > 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.
> 
> My assumption is that the "stable" docs are updated only on a release
> (not necessary a true one, just explaining).
> 
> Dave Brondsema wrote:
> >  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.
> 
> Hmmm, this assumes that we will have more than one line of development,
> like two branches working parallelly. This is not happening ATM, so I
> had not thought of it (not that it should not happpen, just explaining).
> 
> >>['svn://forrest' is used as a short version of
> >>https://svn.apache.org/repos/asf/forrest]
> >>
> >>--------------------
> >>Source SVN space
> >>--------------------
> >>
> >>svn://forrest
> >>           /trunk
> >>              /site (the only website)
> >>
> >>-----------------------------
> >>The published SVN space ...
> >>-----------------------------
> >>
> >>svn://forrest
> >>          /site
> >>             /trunk
> >>             /tags
> >>               /0.6
> >>               /0.7
> 
> >>The site trunk contains
> >>
> >>svn://
> >>   forrest/       
>           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.
> 
> As you see, there is no specification whatsoever of the versions (IOW
> docs and devdocs). Again there is an assumption that we don't use
> versions in the urls as there is only one lone of development (again not
> necessarily ok, just explaining).
> 
> > 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.
> 
> I'll start with the final URLs.
> 
>   http://forrest.apache.org/
>                           **      the contents of the main site
>                           docs/   index.html explains the docs
>                              0.6/     the contents of 0.6 docs
>                              0.7-dev/ the contents of 0.7-dev docs
>                              latest/ (points to 0.7-dev ATM)
>                              stable/ (points to 0.6 ATM)
> 
> Already here we have a problem: if I go to
> 
>    http://forrest.apache.org/docs/latest/
> 
> I will get redirected to
> 
>    http://forrest.apache.org/docs/0.7-dev/
> 
> Then I add a bookmark to that index page and... I'm not linking to the
> latest docs anymore. If I reverse the redirects, I have the same
> problem, only the other way around.
> 

If we use Alias instead of Redirect we don't have this problem.

I would also suggest 'dev' instead of 'latest', because latest could refer to
latest stable or latest development, it isn't clear.  The typical end-user will
probably see "latest" and think latest release.  

> Ok, refining:
> 
>   http://forrest.apache.org/
>                           **      the contents of the main site
>                           docs/   index.html explains the docs
>                              0.6/     the contents of 0.6 docs
>                              trunk/ the contents of 0.7-dev docs
> 
> Ok, so we use version numbers when we define a branch, 'trunk' for the
> trunk (ok, it looks trivial ;-).
> 

'trunk' is a SVN codeline term and I think would be misleading in URLs when
really we just mean the development version.

> Recap:
> 
> --------------------
> Source SVN space
> --------------------
> 
> svn://forrest
>            /trunk
>               /site (the current website)
>               /docs (the current documentation)
>            /branches
>               /0.6
>                 /site (the 0.6 website)
>                 /docs (the 0.6 documentation)
>               /0.5
>                 /site (the 0.5 website)
>                 /docs (the 0.5 documentation)
> 

The source space should only have /docs, not /site.  /site files should be in
the published SVN space.

> -----------------------------
> The published SVN space ...
> -----------------------------
> 
> svn://forrest
>           /site (generated from svn://forrest/trunk/site)

Doesn't this need to be generated from some /docs directory, not some /site
directory?  These "main docs" are a whole forrest site, where is the source for
them held?

>              /docs
>                /trunk (generated from svn://forrest/trunk/docs)
>                /0.6   (generated from svn://forrest/branches/0.6/docs)
> 
> --------------------
> The web space ...
> --------------------
> 
> /www/forrest.apache.org/
> ... the 'svn checkout' of svn://forrest/site/trunk/
> 
> 
> Pros:
> 
> There is a single checkout for the whole site. This makes it easier to 
> update the site.
> 
> The site module remains like now, only with the difference of having the 
> /docs generated from different branches|trunk.
> 
> The only modification to the soure space is that we add a 'docs' dir for 
> the project documentation.
> 
> There is the advantage that the site sources are automatically present 
> in the release, which is not true if we move the site sources outside of 
> the trunk.
> 
> Drawbacks:
> 
> The branches contain a copy of the main site which has to be kept 
> uptodate with the trunk as long as the branch is active.
> 
> Oh wait...
> 
>   - I'm thinking, beware of whacky ideas! ;-) -
> 
> http://svnbook.red-bean.com/svnbook-1.0/ch07s03.html
> 

Let's keep it simple.  Unless there's a huge advantage I think we should avoid
svn:external

-- 
Dave Brondsema : dave@brondsema.net 
http://www.brondsema.net : personal 
http://www.splike.com : programming 
http://csx.calvin.edu : student org 

Mime
View raw message