forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: website documentation version
Date Wed, 03 Nov 2004 10:08:45 GMT
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.

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

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 published SVN space ...
-----------------------------

svn://forrest
          /site (generated from svn://forrest/trunk/site)
             /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

We could do this:

--------------------
Source SVN space
--------------------

svn://forrest
           /site-author (the main website sources)

svn://forrest
           /trunk
              /site (linked to svn://forrest/site)
              /docs (the current documentation)
           /branches
              /0.6
                /site (linked to svn://forrest/site)
                /docs (the 0.6 documentation)
              /0.5
                /site (linked to svn://forrest/site)
                /docs (the 0.5 documentation)

-----------------------------
The published SVN space ...
-----------------------------

svn://forrest
          /site (generated from svn://forrest/site-author)
             /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/

This setting keeps the main site separate from the main forrest dirs, 
but still the generated site is included in any distro we will be doing.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message