forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Brondsema <d...@brondsema.net>
Subject Re: problem with docs at forrest.apache.org/docs/dev/
Date Tue, 05 Apr 2005 16:01:54 GMT
Quoting David Crossley <crossley@apache.org>:

> Ross Gardler wrote:
> > David Crossley wrote:
> > >>Ross Gardler wrote:
> > >>How do people suggest I integrate the plugin docs with the main website
> > >>docs?
> > >
> > >If they went under docs/plugins/$plugin-name/
> > >then they will fit better with the versioning system
> > >described above.
> > 
> > OK, that's where I'll put them then.
> > 
> > I assume we want to SVN them into place in the way I've prototyped (see 
> > commit above), rather than duplicate the xdocs in the docs-author site.
> 
> It would be nice to have the docs available locally too,
> but that sounds hard to achieve. So yes, do what you said.
> 
> > Note, that the point to link into these docs will therefore be 
> > docs/plugins/index.html. That page will contain a link to all the 
> > individual plugin documents.
> > 
> > One more thing that struck me about plugins. We have a potential 
> > nightmare with versioning docs. There are two version numbers we can 
> > work against, the Forrest one and the plugin one. The idea is that 
> > plugins can be release independently of Forrest.
> >
> > So we could have Forrest 0.7 with OK for versions 0.1, 0.2 and 0.3 of 
> > plugin X, whilst 0.4 will only work in Forrest 0.8.
> > 
> > Do we want to worry about maintaining docs for each version of the 
> > plugin as well? For example
> > 
> > f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.1
> > f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.2
> > f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.3
> > f.o.a/0.8/docs/plugins/o.a.f.p.PLUGINNAME/0.4
> > 
> > Note that in this case, if 0.4 of the plugin works in 0.7 of Forrest we 
> > should also have the 0.4 plugin docs in the 0.7 branch. This starts to 
> > get horribly complicated.
> 
> Erk, the same horrid thought ocurred to me.
> 
> I hope that we can get away with just having one set
> of docs for each major version. Let us start with that
> and change it later if we need to. As i say that,
> it sounds very unsatisfactory ... i don't know what to do.
> 

Yes, lets try to keep it simple for now: release the plugins with each major
version.

When that becomes insufficient (e.g. if a plugin takes off and makes its own
major changes & releases within one forrest release), we can tackle it again.  I
think in that case, the plugin should be documented seperately from the main
forrest docs and it can say what versions of forrest it is compatible with.

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