cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: [RT] doco lite?
Date Wed, 27 Oct 2004 01:38:03 GMT
Upayavira wrote:
> Bertrand Delacretaz wrote:
> > Upayavira a écrit :
> >
> >> ...The thing you seem to have missed is the staging process. If I 
> >> have written an xdoc, I want to see that as HTML, on a staging 
> >> server, before I actually publish it. After all, the XML might not 
> >> even be valid,

As always, people need to do xml validation prior to commit.

> or there might be mistakes. I need to be able to see 
> >> the page on the site before I publish it...


> > How about using SVN tags for this?
> >
> > -Current known good version of the docs is always tagged as 
> > "current-docs"
> > -Website serves this tagged version on the public site
> > -New docs releases are done by moving this tag to the appropriate 
> > revision (I didn't try moving tags in SVN yet but it shouldn't be a 
> > problem)
> >
> > Then you'd use the current release for the staging process, and update 
> > the public version by moving the SVN tag.
> So you'd use HEAD or whatever to view the latest commit, and the public 
> would see the "current-docs" tag. That could work. But would we want the 
> HEAD to be password protected, or in some way hidden so that it doesn't 
> get regularly viewed when it isn't live yet? I like the idea of being 
> able to tag the docs whenever we release. If we can get the available 
> tags for a document from SVN, we could have a dropdown that allows you 
> to see the docs for a specific version, which would be absolutely 
> fantastic. That would solve soooooo many problems.
> So, when do you start?

The website is currently built from the release version,
so i presume that that is HEAD of the branch.

So we would have two separate instances of Cocoon (or Forrest).
One is the staging server, which is the head. The other is the
live site, which uses the "current-docs" tag.

The same would happen for the proposed "Cocoon Samples" site.

I do see some issues with this proposal. When one edits a
single document, they can click and view, and will be able
to see any structural and content problems. When one edits
a heap of documents, then would need to click on each doc
to see if it works.

Broken internal links are not apparent by just looking.

One thing to bear in mind, people can still run the
'./ cli -x cli.xconf' or './ docs'
locally to reveal global issues. Actually the "Forrestbot"
proposal can still apply here too. People can still use
that to trigger a complete website build, via the online
interface and can review the build log for issues. Just
they would not use the "deploy" phase of Forrestbot.

Does SVN enable us to "move" tags? If not, then this
proposal might fail. We could not have a new tag
for every little documentation tweak.

David Crossley

View raw message