Uses Cases for Change Log management features of org.apache.forrest.plugin.input.projectInfo Write status.xml File

Status.xml if an XML file that records the actions that have been taken in each release of a project. You can then generate a Change Log from that file using the projectInfo plugin.

Justification

Provide a central location and a semi-structured format for recording actions taken during project development. This file can then be used to generate various views on the changes in a release. For example:

  • Changes between releases
  • Developers involved in a release
  • Release notes
 Create/open a status.xml file

In your favourite XML editor either create a new file or open an existing status.xml file. The default location of these files within a Forrest content object is in the project root. This file should conform to one of the status.xml schemas. The root element for this document is status.

 You have either a blank status.xml document or an existing one ready for editing. Create a developer list

In order to attribute changes to a specific developer it is neceessary to create a developers element. Within this element you should add a single person element for each develop who works on the project.

 Each developer is identified in the status.xml file. Create a contexts list

Each action within a release is given a context to help classify changes. When reports are created the context of an action is used to create a more readable report in which similar actions are grouped together. You can specify any contexts you like within the contexts element.

Common contexts used in an software development project are:

]]> The status.xml file describes the sufficient contexts to group common actions together. Create a changes element

Actions that describe the changed in a release are placed within a changes.

 Status.xml holds an changes element that will group all release information. Create a release element

The details of each release are enclosed within a release element, so you need to create that now.

 You have the container for your current development release. Create a notes element

Each release can have a notes section. This is used to provide descriptive text at the start of many reports. The notes should describe the release in fairly high level detail, it should not describe any change descriptions, these will be added in the next step.

 You have a user focussed description of the project and this release. Add actions taken during the development cycle

During the development cycle for the release action elements should be added for each significant contribution to the release.

If the change is of particular significance and you woul dlike it to appear in the release notes generated by the projectInfo plugin you should set the importance attribute to "high".

 Each significant change in this development cycle is describe in a action element. Generate the change log

To generate a changelog from your status.xml file you need to request /changes.html or changes.pdf or whatever format you have enabled within Forrest using output plugins.

Note that the projectInfo plugin provides a special RSS output format of. Technically, this should not be part of an input plugin and therefore it may be moved at a later date. However, you will always be able to generate the RSS feed by requesting changes.rss.

You can generate a change log for a specific version by specifying a version number in the request, for example, changes_0.1.html.

 Your project is able to generate a changelog.