This plugin generates project info from various configuration files.
By maintaining a file called status.xml you can manage a list
changes to your code base. This list can then be generated as a changes
page and/or an RSS feed of those changes. For example, here are the
changes for this plugin, here is the same
list of changes as an RSS feed.
It's possible to limit the displayed changes to a particular version number as well. For example, here are the changes for version 0.1 of this plugin (and as an RSS feed).
If you want to only retrieve the changes for the most recent version of the project then you can do that too. Here are the changes in the current development version of this plugin (and once more as an RSS feed).
You can generate as well the changes with svn. For this you need to
point forrest to the directory where the svn logs are. The defaut is
set to {properties:content}svn-log/ and you can change it by
setting projectInfo.svn.log.dir in your project
locationmap.
We created a log file for demonstration with the following command:
This file reflect all changes that have been done to this plugin. You can see the result log.svn.html.
You see the only context we have definied is "code". This is
controlled by a mapper file. The defaut is set to
{properties:content}path-to-context.xml and you can change it
by setting projectInfo.svn.mapper in your project
locationmap.
If the log file is growing, one is looking into splitting the file. You can find out the revision number of the first and last commit of a month within the log by requesting log.svn-revision.xml.
We implemented as well a small svn cli output to generate log files
per month log.svn-sh.xml. The defaut url is set to
http://svn.myHost.org/repos and you can change it
by setting project.svn.url in your project
locationmap.
The status.xml file can also be used to manage a list of todo items for the community. For example, here is a psuedo todo list for this plugin (our real todo list is managed in an Issue Tracker, one day we hope to add support for that here too).
To produce release notes you must maintain a status.xml file
for your project and request a page with an URL such as
http://domain.com/releaseNotes_0.7-dev.html, this will be produce
the release notes for 0.7-dev.
If the version number ends with -dev a warning will be included
in the generated page, informing the reader that it is a development version and
therefore the list of changes is incomplete.
For a status.xml action toi be included in the
release notes it must have an attribute importance="high". When
writing actions in status.xml you should write them with the
following two questions in mind:
The introductory text in the release notes comes from the (optional)
element notes (a child of the release element).
The status.xml file can also contain a list of committers and contributors which can, optionally, be displayed as part of the changes file.
At the time of writing this functionality is quite minimal, being just a list of authors at the end of the changes document. However, in future releases it is intended that a more configurable output will be available.
It may be that some items have been contributed by authors other
than those listed in the developer list. These are accredited in a
due-to attribute of the action element in
status.xml. A list of this contributors is made available at the
end of the release notes for each version.
Projects can manage a document describing various use cases for the application. These use cases can then be used to generate useful developer and user documentation, as well as helping to track the implementation status of features.
Some of the uses of this feature are:
To see some examples take a look at:
Project details are generated from a project descriptor file. This file can be in any of the followin formats:
The location of this descriptor file is specified in the locationmap
with the hint pproject.descriptor. This defaults to
the root of your projects content directory. To place your descriptor
in a different location simply add
a matcher like that shown below in your projectInfo.locationmap-projects
file. This file is, by default, in the root of the webapp directory.
To retrieve the project details page request the file
/projectDetails.html.
You can use the projectInfo plugin to pull together project information for multiple projects. For example, take a look at the project details for Apache Forrest.
Using the locatoinmap you can retrieve this content from anywhere you want, for example, the DOAP file for the Forrest project comes from directly from SVN, thus we are always assured of it being up to date.
To retrieve the project details of another project make a request
for projectDetails/projectDetails.[PROJECT_NAME].html. For this to work
your project locationmap muest have an entry like this:
Of course, if you have a central location for all your project descriptor files you could use a match like this:
The system will automatically create an index of projects from your projects locationmap file. For example, the "Projects" section of the navigation on the left is automatically generated.
These features are operational, however, they are not fully developed and may change considerably before they become part of the official feature set. You can use them, but be prepared for changes, possibly without warning. If you do use these features we recomend that you join the developers mailing list.
This plugin uses an experimental properties system that allows plugins
to expose configuration information to the project. It is likely that at
least some of these configuration options will eventually move into Dispatcher
based contracts. In the meantime, you can use this config system to control
some aspects of the display information. See the
forrest.properties.xml file for a description of the config
options available. To alter the configuration simply override these
properties in your projects forrest.properties.xml file.