Uses Cases for Change Log management features of org.apache.forrest.plugin.input.projectInfo

Return-Path: Delivered-To: apmail-forrest-svn-archive@www.apache.org Received: (qmail 12989 invoked from network); 10 Apr 2007 00:20:38 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 10 Apr 2007 00:20:38 -0000 Received: (qmail 88497 invoked by uid 500); 10 Apr 2007 00:20:44 -0000 Delivered-To: apmail-forrest-svn-archive@forrest.apache.org Received: (qmail 88460 invoked by uid 500); 10 Apr 2007 00:20:44 -0000 Mailing-List: contact svn-help@forrest.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Forrest Developers List" List-Id: Delivered-To: mailing list svn@forrest.apache.org Received: (qmail 88451 invoked by uid 99); 10 Apr 2007 00:20:44 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 17:20:44 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 17:20:34 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id 98DB91A9844; Mon, 9 Apr 2007 17:20:13 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r526968 [3/3] - in /forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo: ./ resources/stylesheets/ src/documentation/ src/documentation/content/ src/documentation/content/svn-log/ src/documentation/content/useCases/ src/docume... Date: Tue, 10 Apr 2007 00:20:10 -0000 To: svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070410002013.98DB91A9844@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/changeLogFeatures.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/changeLogFeatures.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/changeLogFeatures.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/changeLogFeatures.xml Mon Apr 9 17:20:08 2007 @@ -17,63 +17,70 @@ --> 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.

- +

+ 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:

- +

+ 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.

+ 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.

+ 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:

- + 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: +

+ + @@ -81,78 +88,91 @@ - ]]> + ]]> + 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.

+ 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.

+ 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 + + 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 + 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. - + + + 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. + Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/useCaseFeatures.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/useCaseFeatures.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/useCaseFeatures.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/useCases/useCaseFeatures.xml Mon Apr 9 17:20:08 2007 @@ -17,24 +17,27 @@ --> Uses Cases for the Use Case management features of org.apache.forrest.plugin.input.projectInfo - Write Use Case Documentation -

Write semi-structured use case documents so that they can be reused in a variety of ways. - This use case describews a process for writing such documents. This document is derived from - such a source document.

- +

+ Write semi-structured use case documents so that they can be reused in a + variety of ways. This use case describews a process for writing such + documents. This document is derived from such a + source document. +

Justification - -

A use case describes a unit of work. It is typically used in the design - stages of a software project. It is very useful for describing what an applicaiton must - do and what patchs through the system can be taken.

- -

By bringing this information together in a semi-structured document we can use it in many - different ways. For example:

- +

+ A use case describes a unit of work. It is typically used in the + design stages of a software project. It is very useful for describing + what an applicaiton must do and what patchs through the system can be + taken. +

+ By bringing this information together in a semi-structured document we + can use it in many different ways. For example: +

Requirements Documentation
Developer Documentation
Task Lists

- - Create/open a Use Case file - In your favourite XML editor either create a new file - or open an existing use case file. The default location of these files - within a Forrest content object is /content/documentation/useCases/**.xml + + In your favourite XML editor either create a new file or open an + existing use case file. The default location of these files within a + Forrest content object is + /content/documentation/useCases/**.xml You have either a blank use case document or an existing one ready for editing. - - Create a DTD for use case descriptions. - Aggregate all documents in the useCases directory to provide - ne large document describing all use cases. + + Create a DTD for use case descriptions. + + + Aggregate all documents in the useCases directory to provide ne large + document describing all use cases. + - Create a new use case -

A use case is enclosed within a useCase element. - Each use case should be given a brief title to describe it.

- +

+ A use case is enclosed within a useCase element. Each + use case should be given a brief title to describe it. +

- You have the container for your new use case. - - - Describe the overall objective of the use case - -

Each use case should be described in terms of:

The objective
The expected results
The justification

This information should be placed in the description element - of your use case. This node allows any XDoc markup and therefore you are - reasonably free to use whatever formatting or images are needed to convey the - important details most efficiently.

- - - You have a use case that is described sufficiently well for an average user of the end system + + Describe the overall objective of the use case + +

+ Each use case should be described in terms of: +

The objective
The expected results
The justification

+ This information should be placed in the description + element of your use case. This node allows any XDoc markup and + therefore you are reasonably free to use whatever formatting or + images are needed to convey the important details most efficiently. +

+ + You have a use case that is described sufficiently well for an average user of the end system to understand its purpose. - - - - Define each step in the Use Case - -

Each use case will be subdivided into one or more steps that must be carried out - in order to complete the task. Each of these steps is defined within a step - element which are chilren of a steps element.

- - - - - Descripbe the step - -

Each step has a title and a description. The description should provide enough information - for a user to complete the task and for a developer to implement support for the user in that - task.

- -

In addition each step can be described as required or optional. By default a step is assumed - be required. To set it to optional add a required="false" attribute to the - step element.

- - - A user will be able to follow instructions on how to carry out the step. - + + + Define each step in the Use Case + +

+ Each use case will be subdivided into one or more steps that must be + carried out in order to complete the task. Each of these steps is + defined within a step element which are chilren of a + steps element. +

+ + + + Descripbe the step + +

+ Each step has a title and a description. The description should + provide enough information for a user to complete the task and for a + developer to implement support for the user in that task. +

- - Describe the expected results - -

Provide, within a result a brief description of the expected results from - this step. This should summarise what state the application will be in once this use case - has been performed.

- - You will have provided enough information to allow developers to test the functionality and +

+ In addition each step can be described as required or optional. By + default a step is assumed be required. To set it to optional add a + required="false" attribute to the step + element. +

+ + A user will be able to follow instructions on how to carry out the step. + + + Describe the expected results + +

+ Provide, within a result a brief description of the + expected results from this step. This should summarise what state + the application will be in once this use case has been performed. +

+ + You will have provided enough information to allow developers to test the functionality and users to identify when a step has been succesfully completed. - - - - Add "fixme" notes - -

A fixme note is enclosed within a fixme element. It describes something that - remains to be done within this step. Each fixme has a priority attribute which can take one of - of the followin values:

- -

Enhancement - a nice to have ehancment that may or may not be implemented.
Low - this is considered an important addition to the use case, but everything works without it.
High - this is an important addition. Everything works without it, but having this implmeneted would + +
+ Add "fixme" notes +
+
+ A fixme note is enclosed within a fixme element. It + describes something that remains to be done within this step. Each + fixme has a priority attribute which can take one of of the followin + values: +
+
- Enhancement - a nice to have ehancment that may or may not be implemented.
- Low - this is considered an important addition to the use case, but everything works without it.
- High - this is an important addition. Everything works without it, but having this implmeneted would improve the application considerably.
- Major - this is nor preventing work that utilises the use case, but it is considered a requirement +
- Major - this is nor preventing work that utilises the use case, but it is considered a requirement for the next release since it adds key functionlaity.
- Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP
- -
Although this step is optional, it is good practice to allways add a - <fixme priority="blocker">Not yet implemented</fixme> - element to all new steps. This is becuase these nodes will be used to build a - functionality matrix later on.
-
- - Users will be able to understand to what degree a step is implemented and developers will be able to +
Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP

+ Although this step is optional, it is good practice to allways add a + <fixme priority="blocker">Not yet + implemented</fixme> element to all new steps. This is + becuase these nodes will be used to build a functionality matrix + later on. +

+ + Users will be able to understand to what degree a step is implemented and developers will be able to see what remains to be done. - - All fixmes to link to an issue tracker entry - - - - Add alternatives - -

Sometimes there will be alternative paths through each step. These can be described in an - alternatives element that allows free-form XDoc content. However, please be - careful, if an alternative is more than a simple variation you may want to consider a - whole new use case for the alternative.

- - - Minor variations in the path through a use case will be documented for your users. - - - - Write Implementation Notes - -

Developer implementation notes for each of the steps should be added either when writing the - initial use case or later during the development phases of the use case. These notes are for technical readers - and are intended to help those who come after the initial author to get a starting point when inspecting how - a feature is implemented. It is not intended that these notes will contain full implementation details, only an - overview should be provided.

- - - A technical reader will be able to gain a baisc understanding of how each step is implemented in the + + All fixmes to link to an issue tracker entry + + + + Add alternatives + +

+ Sometimes there will be alternative paths through each step. These + can be described in an alternatives element that allows + free-form XDoc content. However, please be careful, if an + alternative is more than a simple variation you may want to consider + a whole new use case for the alternative. +

+ + Minor variations in the path through a use case will be documented for your users. + + + Write Implementation Notes + +

+ Developer implementation notes for each of the steps should be added + either when writing the initial use case or later during the + development phases of the use case. These notes are for technical + readers and are intended to help those who come after the initial + author to get a starting point when inspecting how a feature is + implemented. It is not intended that these notes will contain full + implementation details, only an overview should be provided. +

+ + A technical reader will be able to gain a baisc understanding of how each step is implemented in the application. - + - Generate Use Case Documentation for Developers - -

Generate a complete list of all use cases for a project in a format useful to - developers of the application. This list is to include:

- +

+ Generate a complete list of all use cases for a project in a format + useful to developers of the application. This list is to include: +

a description of the use case
a summary of each of the steps involved
full details of each of the steps
a description of the expected outcome of each step
details of common alternatives in each step
implementation notes for each step
implementation notes for each step

Justification -

A use case describes a unit of work. It is typically used in the design - stages of a software project, however, they can often be useful in creating - user documentaiton. Especially when they describe user interface functionality.

- - Unfortunately this use case document does not currently cover all functions - of the plugin since this functionlaity was added after many other features. Whilst you - are exploring this feature, why not add a use case to the plugin and submit a patch - so that those coming after you can enjoy more complete documentation. +

+ A use case describes a unit of work. It is typically used in the + design stages of a software project, however, they can often be useful + in creating user documentaiton. Especially when they describe user + interface functionality. +

+ + Unfortunately this use case document does not currently cover all + functions of the plugin since this functionlaity was added after many + other features. Whilst you are exploring this feature, why not add a + use case to the plugin and submit a patch so that those coming after + you can enjoy more complete documentation. +

- Make HTTP request

- Request - http://localhost:8888/docs/developer/useCases.xml + Request http://localhost:8888/docs/developer/useCases.xml

@@ -225,38 +245,48 @@ An XDoc is created that describes the use cases

- - Make the summary optional - already added - $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap. - + + Make the summary optional - already added $includeImplementationNotes + parameter to stylesheet. Need to pass value form sitemap. + -

Depending on what plugins are available within your running instance of Forrest you will - be able to request different output formats as per the usual Forrest usage. For example requesting - a http://localhost:8888/docs/developer/useCases.html will generate the HTML document, whilst - http://localhost:8888/docs/developer/useCases.pdf will generate the PDF document (as long - as you have the relevant plugins installed).

+ Depending on what plugins are available within your running instance + of Forrest you will be able to request different output formats as + per the usual Forrest usage. For example requesting a + http://localhost:8888/docs/developer/useCases.html will generate the + HTML document, whilst + http://localhost:8888/docs/developer/useCases.pdf will generate the + PDF document (as long as you have the relevant plugins installed). +

- -

The source document for use cases is, by default, called useCases.xml and is - located in the root of the projects xdocs directory.

- -

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to - /docs/developer/useCases.xml results in the useCases.xml file being translated into an XDoc as per - the usual forrest processing. See the input.xmap file fo this plugin,

+ The source document for use cases is, by default, called + useCases.xml and is located in the root of the + projects xdocs directory. +

+ +

+ The URL space docs/**/useCases.xml is reserved for + the projectInfo plugin. A request to /docs/developer/useCases.xml + results in the useCases.xml file being translated into an XDoc as + per the usual forrest processing. See the input.xmap file fo this + plugin, +

- Generate Use Case Documentation for Users - -

Generate a complete list of all use cases for a project. This list is to include:

- +

+ Generate a complete list of all use cases for a project. This list is to + include: +

a description of the use case
a summary of each of the steps involved
a description of the expected outcome of each step
details of common alternatives in each step

Justification -

- - Unfortunately the use case document does not currently cover all functions - of the plugin since this functionlaity was added after many other features. Whilst you - are exploring this feature, why not add a use case to the plugin and submit a patch - so that those coming after you can enjoy more complete documentation. +

+ + Unfortunately the use case document does not currently cover all + functions of the plugin since this functionlaity was added after many + other features. Whilst you are exploring this feature, why not add a + use case to the plugin and submit a patch so that those coming after + you can enjoy more complete documentation. +

- Make HTTP request

- Request - http://localhost:8888/docs/user/useCases.xml + Request http://localhost:8888/docs/user/useCases.xml

@@ -292,46 +324,60 @@ An XDoc is created that describes the use cases

- - Enable the retrieval of a specific use case rather than all at once. - Make the summary optional - there is a switch in the XSL for this, just need to pass a property - from the XMAP - + + Enable the retrieval of a specific use case rather than all at once. + + + Make the summary optional - there is a switch in the XSL for this, + just need to pass a property from the XMAP + -

Depending on what plugins are available within your running instance of Forrest you will - be able to request different output formats as per the usual Forrest usage. For example requesting - a http://localhost:8888/docs/user/useCases.html will generate the HTML document, whilst - http://localhost:8888/docs/user/useCases.pdf will generate the PDF document (as long - as you have the relevant plugins installed).

+ Depending on what plugins are available within your running instance + of Forrest you will be able to request different output formats as + per the usual Forrest usage. For example requesting a + http://localhost:8888/docs/user/useCases.html will generate the HTML + document, whilst http://localhost:8888/docs/user/useCases.pdf will + generate the PDF document (as long as you have the relevant plugins + installed). +

- -

The source document for use cases is, by default, called useCases.xml and is - located in the root of the projects xdocs directory.

- -

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to - /docs/user/useCases.xml results in the useCases.xml file being translated into an XDoc as per - the usual forrest processing, see input.xmap for more details.

+ The source document for use cases is, by default, called + useCases.xml and is located in the root of the + projects xdocs directory. +

+ +

+ The URL space docs/**/useCases.xml is reserved for + the projectInfo plugin. A request to /docs/user/useCases.xml + results in the useCases.xml file being translated into an XDoc as + per the usual forrest processing, see input.xmap for more details. +

- Generate a Functionality Matrix -

If a use case document is correcly marked up with fixme elements it is possible - to create a functionality matrix for each use case. This will show how complete the implementation - of a use case is.

- -

A table can be created which shows each of the steps in a use case, each step can be given a - count for the bumber of fixme items outstanding on each of the steps. Furthermore, since each - fixme is given a priority we can clearly indicate which use cases are operational an - hich are not.

+ If a use case document is correcly marked up with fixme + elements it is possible to create a functionality matrix for each use + case. This will show how complete the implementation of a use case is. +

+ +

+ A table can be created which shows each of the steps in a use case, each + step can be given a count for the bumber of fixme items outstanding on + each of the steps. Furthermore, since each fixme is given a + priority we can clearly indicate which use cases are operational an hich + are not. +

- Make HTTP request @@ -343,34 +389,45 @@

- An XDoc is created that lists the steps in each use case and identifies the status - of each use case. + An XDoc is created that lists the steps in each use case and + identifies the status of each use case.

- - Not Implemented Yet - although the user and dev use case documents - do show the status of each step in the details table and implementation notes. - + + Not Implemented Yet - although the user and dev use case documents do + show the status of each step in the details table and implementation + notes. + -

Depending on what plugins are available within your running instance of Forrest you will - be able to request different output formats as per the usual Forrest usage. For example requesting - a http://localhost:8888/docs/developer/featureMatrix/useCases.html will generate the HTML document, whilst - http://localhost:8888/docs/developer/featureMatrix/useCases.pdf will generate the PDF document (as long - as you have the relevant plugins installed).

+ Depending on what plugins are available within your running instance + of Forrest you will be able to request different output formats as + per the usual Forrest usage. For example requesting a + http://localhost:8888/docs/developer/featureMatrix/useCases.html + will generate the HTML document, whilst + http://localhost:8888/docs/developer/featureMatrix/useCases.pdf will + generate the PDF document (as long as you have the relevant plugins + installed). +

- -

The source document for use cases is, by default, called useCases.xml and is - located in the root of the projects xdocs directory.

- -

The URL space docs/**/useCases.xml is reserved for the projectInfo plugin. A request to - /docs/developer/featureMatrix/useCases.xml results in the useCases.xml file being translated into an XDoc as per - the usual forrest processing. See the input.xmap file fo this plugin,

+ The source document for use cases is, by default, called + useCases.xml and is located in the root of the + projects xdocs directory. +

+ +

+ The URL space docs/**/useCases.xml is reserved for + the projectInfo plugin. A request to + /docs/developer/featureMatrix/useCases.xml results in the + useCases.xml file being translated into an XDoc as per the usual + forrest processing. See the input.xmap file fo this plugin, +

- Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml Mon Apr 9 17:20:08 2007 @@ -16,168 +16,198 @@ limitations under the License. --> - -

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

- + +

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

Apache Forrest - org.apache.forrest.plugin.input.projectInfo Plugin -

This plugin generates project info from various configuration files.

+ This plugin generates project info from various configuration files. +

Changes -

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).

- +

+ 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). +

SVN Changes -

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:

+ 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.

- +

+ 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. +

+ + /forrest -]]> -

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.

+]]> + +

+ 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. +

To Do List -

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).

+ 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). +

Release Notes -

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:

- +

+ 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 same options with respect to retrieveing specific versions of the - release notes are available as with the changes feature (discuseed above). +

+ The introductory text in the release notes comes from the (optional) + element notes (a child of the release + element). +

+ + The same options with respect to retrieveing specific versions of the + release notes are available as with the changes feature (discuseed + above). +

Developers List -

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.

- +

+ 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.

+ 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. +

- -

Use Cases -

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:

- +

+ 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:

- +

+ 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

Experimental Features -

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.

- +

+ 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.

- +

+ 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. +

Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml Mon Apr 9 17:20:08 2007 @@ -15,7 +15,6 @@ See the License for the specific language governing permissions and limitations under the License. --> - - - @@ -43,10 +40,8 @@ - - @@ -57,18 +52,16 @@ - + - - - @@ -79,5 +72,4 @@ - Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/tabs.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/tabs.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/tabs.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/tabs.xml Mon Apr 9 17:20:08 2007 @@ -16,13 +16,11 @@ limitations under the License. --> - - - - - - Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/skinconf.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/skinconf.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/skinconf.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/skinconf.xml Mon Apr 9 17:20:08 2007 @@ -15,16 +15,13 @@ See the License for the specific language governing permissions and limitations under the License. --> - ]> - &skinconf-common; Plugin: projectInfo input org.apache.forrest.plugin.input.projectInfo plugin for Apache Forrest - Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_en.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_en.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_en.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_en.xml Mon Apr 9 17:20:08 2007 @@ -16,5 +16,5 @@ limitations under the License. --> - + Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_es.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_es.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_es.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/translations/ProjectInfoMessages_es.xml Mon Apr 9 17:20:08 2007 @@ -16,6 +16,6 @@ limitations under the License. --> - - + + Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml URL: http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml?view=diff&rev=526968&r1=526967&r2=526968 ============================================================================== --- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml (original) +++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml Mon Apr 9 17:20:08 2007 @@ -17,43 +17,42 @@ --> - - + - + - + - - + --> - - - - - - - + + + + + + - + -