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
