Welcome to the org.apache.forrest.plugin.input.projectInfo Plugin

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:

cd forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo
svn log --xml -v . > src/documentation/content/svn-log/log.svn.xml

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.

<paths>
  <path context="Code">/forrest</path>
</paths>
      

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:

• should it be importance="high"?
• will the action read correctly in the release notes?

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.

Contributor List

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:

• during design - what needs to be done
• during development - what needs to be done/has been done
• during use - user documentation of common activities
• during maintenance - how something was implemented

To see some examples take a look at:

• User Docs for the Use Case features of this plugin
• Developer Docs for the Use Case features of this plugin

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.

Configuration

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.