plugins/RELEASE_PROCESS.txt

Because plugin versions are managed by Forrest automatically it is possible 
to deploy and/or release individual plugins independantly of Forrest and 
other plugins. Before we discuss this process lets first look at the difference
between releasing a plugin and deploying a plugin.

Deploy or Release?
------------------

Plugins are automatically downloaded and installed whenever they are needed by a 
Forrest project. In order for this to happen it is necessary to deploy the
plugin to a download server. Plugins may be deployed at any time during their
development cycle, that is a developer may choose to deploy a plugin that has not
yet been fully tested. This enables the plugin to be tested "in the field", by
its users.

Since users are able to opt to use a specfic version of a plugin those working in
production environments can ensure that these interim test deployments do not 
affect their work.

Releasing a plugin is the act of deploying a fully tested plugin available for use.
This process will generally be more than just making the plugin available via a 
download site, it will usually involve making public announcements, tagging the 
source tree, incrementing version numbers and other such maintenance tasks.

Deploying a Plugin
------------------

By convention a plugin that has not been fully tested will have '-dev' appended 
to the version number in the plugins build.xml file.

To deploy on the Apache Forrest download server you will need to be a committer.
Simply change directory to the plugin home directory and deploy the plugin
by doing 'tools/ant/bin/ant deploy' [1]. The build system will take care of
everything else for you.

Deployment is carried out with the command "ant deploy". Since this does not
affect releaed versions of the plugin it can be run at any time (note some minimal 
tests are done during the deploy process). 

[1] See the note about using our own version of Ant:
http://forrest.apache.org/docs/dev/howto/howto-buildPlugin.html#ant

Releasing a Plugin
------------------

The only difference between deploying and releasing a plugin from the point of
view of making the download available is that the plugin version number will
have the '-dev' postfix removed in build.xml before the "ant deploy" target is
run.

Once the deployment is complete the version number should be increased and the 
'-dev' postfix will be appended.

To release a plugin one should run the command "ant release", however, there is 
more to it than this.

TODO: Describe voting procedure
TODO: announcement emails
TODO: tagging source tree

FAQs
====

What if a new feature breaks compatability with a released version of Forrest?
------------------------------------------------------------------------------

If you add a feature to a plugin that will break compatability with a released version of
Forrest then you should up the forrest version number in the plugins build.xml file. This
will prevent the new version of the plugin being made avialble to the older version of 
Forrest.

However, you might light to consider doing a release of the plugin before you break 
compatability. It depends on what other changes there are to the plugin before you
start your work. It is always best to raise this on the dev list.