forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: versioned plugin docs (Was: svn commit: r190111)
Date Mon, 13 Jun 2005 15:45:30 GMT
Ross Gardler wrote:
> David Crossley wrote:
> 
>> David Crossley wrote:
> 
> 
> ..
> 
>>>> If my understanding is correct we can achieve direct links to 
>>>> versioned plugin docs. However, with the unversioned plugin docs you 
>>>> have created here we cannot provide a versioned set of docs.
>>
>>
>>
>> We were hoping that we could solve this today, but it seems that Ross 
>> is busy
>> on other things. We can attend to this later, as building the release is
>> not dependent on the deploying of the versioned plugins docs.

...

> All I need to know at this stage is what directory should the plugin 
> docs be published to on the website SVN server. I will change the plugin 
> build script accordingly and publish all plugins in order to republish 
> the docs and deploy the versioned zips for download.

Given the timeframe of this Ferdinand, myself and David cheated today 
and had a Skype conversation to confirm our collective understanding of 
this thread. This mail is to summarise what was said for the benefit of 
the community as a whole. As it happens, the solution we have decided to 
go with is one that has already been discussed on this list, but 
nevertheless, a summary is appropriate.

First let me summarise the problem:

Keeping versioned documents for plugins is difficult since there can be 
multiple versions of the plugins and each version will work in one or 
more version of Forrest. In addition guiding the user to the right page 
with sensible navigation is a non-trivial issue.

We have decided to keep the plugins documentation completely separate 
from the Forrest documentation. It is already conceptually separate in 
that it is developed within the plugin itself and published 
independently of Forrest. However, until the considerable efforts of 
David and Ferdinand this weekend they were embedded within the versioned 
docs for plugins. That is they were sub folders of the docs/0.7 or 
docs/0.8 folders.

In this new documentation branch we will be publishing the plugin docs 
to a separate directory structure. We will have one directory for each 
major Forrest release (i.e. 0.7, 0.8, 0.9 and so on). Within each of 
these directories there will be an index page showing the plugins that 
are available for that version of Forrest.

The end result will be, for example:

http://f.a.o/docs/ will refer to the docs for current version of Forrest

http://f.a.o/docs_070/ will refer to the documentation for Forrest V0.7

http://f.a.o/plugins/index.html will be the index of valid plugins for 
the current release version of Forrest

http://f.a.o/plugins_070/index.html will be the index of valid plugins 
for the 0.7 version of Forrest

http://f.a.o/plugins_080/index.html will be the index of valid plugins 
for the 0.8 version of Forrest

http://f.a.o/plugins_070/PLUGINNAME will be the latest docs for the most 
recent release of the indicated plugin for version 0.7 of Forrest

http://f.a.o/plugins_080/PLUGINNAME will be the latest docs for the most 
recent release of the indicated plugin for version 0.8 of Forrest

We decided against keeping *all* version docs for plugins since plugins 
are small units of functionality and changes to plugins within a single 
release of Forrest (i.e. no major changes to core) are unlikely to 
result in major changes to a plugin. Where major changes to plugins are 
likely to be seen is between versions of Forrest. For example, 0.7 
Forrest does not have locationmap, 0.8 does. This is significantly 
changing the way the Daisy plugin works between 0.7 and 0.8

To implement this I will need to make some minor changes to the plugin 
build system and the plugins.xml file (these are only really config 
changes). I will prepare a patch and call a vote against it since we are 
currently in code freeze.

I hope that about covers it. I'm sure David or Ferdinand will 
correct/clarify where necessary.

Whilst I am at it, can I take the opportunity to thank David and 
Ferdinand. Trying to get these docs sensibly structured has been a major 
task, one that I would not liked to have tackled. A round of applause 
for our tireless housekeepers please...

Ross

Mime
View raw message