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

+ +

Summary

+Create/open a status.xml file +
+Create a developer list +
+Create a contexts list +
+Create a changes element +
+Create a release element +
+Create a notes element +
+Add actions taken during the development cycle +
+Generate the change log +

+ +

Details

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Description	Result	Status
1. 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.	Implemented
2. 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.	Implemented
3. 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: + + +<contexts> + <context id="code" title="Changes to the Code Base"/> + <context id="docs" title="Changes to Documentation"/> + <context id="admin" title="Changes to Project Administration"/> + <context id="design" title="Changes to Design"/> + <context id="build" title="Changes to Build"/> +</contexts> + + +	The status.xml file describes the sufficient contexts to group common + actions together.	Implemented
4. 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.	Implemented
5. 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.	Implemented
6. 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.	Implemented
7. 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.	Implemented
8. 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.	Implemented

+ +

Implementation Notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Notes
1. Create/open a status.xml file	+ +
2. Create a developer list	+ +
3. Create a contexts list	+ +
4. Create a changes element	+ +
5. Create a release element	+ +
6. Create a notes element	+ +
7. Add actions taken during the development cycle	+ +
8. Generate the change log	+ +

+ +

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.

+ +

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:

Requirements Documentation
Developer Documentation
User Documentaiton
Functionality Matrices
Task Lists

+ +

Summary

+Create/open a Use Case file +
+Create a new use case +
+Describe the overall objective of the use case +
+Define each step in the Use Case +
+Descripbe the step +
+Describe the expected results +
+Add "fixme" notes (Optional)
+Add alternatives (Optional)
+Write Implementation Notes (Optional)

+ +

Details

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Description	Result	Status
1. 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 +	You have either a blank use case document or an existing one ready for editing.	+ Implemented with fixmes:- + High: 1 +
2. 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. + + +	You have the container for your new use case.	Implemented
3. 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.	Implemented
4. 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. + +		Implemented
5. 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.	Implemented
6. 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.	Implemented
7. Add "fixme" notes (Optional)	+ + 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 + 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 + see what remains to be done.	+ Implemented with fixmes:- +
8. Add alternatives (Optional)	+ + 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.	Implemented
9. Write Implementation Notes (Optional)	+ + 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.	Implemented

+ +

Implementation Notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Notes
1. Create/open a Use Case file	+ + + Fixme (High) + Aggregate all documents in the useCases directory to provide + ne large document describing all use cases. + +
2. Create a new use case	+ +
3. Describe the overall objective of the use case	+ +
4. Define each step in the Use Case	+ +
5. Descripbe the step	+ +
6. Describe the expected results	+ +
7. Add "fixme" notes	+ +
8. Add alternatives	+ +
9. Write Implementation Notes	+ +

+ +

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:

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

+ +

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.

Warning

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.

+ +

Summary

+Make HTTP request +

+ +

Details

+ + + + + + + + + +

Step	Description	Result	Status
1. Make HTTP request	+ + + Request + http://localhost:8888/docs/developer/useCases.xml + + +	+ + + An XDoc is created that describes the use cases + + +	+ Implemented with fixmes:- + High: 1 +

+ +

Implementation Notes

+ + + + + + + + + +

Step	Notes
1. Make HTTP request	+ + 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, + + + + Fixme (High) + Make the summary optional - already added + $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap. + +

Step

Notes

1. Make HTTP request

+ +

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,

+ +
+

Fixme (High)

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

+ +

Generate Use Case Documentation for Users

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
full details of each of the steps
a description of the expected outcome of each step
details of common alternatives in each step

+ +

Justification

Warning

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.

+ +

Summary

+Make HTTP request +

+ +

Details

+ + + + + + + + + +

Step	Description	Result	Status
1. Make HTTP request	+ + + Request + http://localhost:8888/docs/user/useCases.xml + + +	+ + + An XDoc is created that describes the use cases + + +	+ Implemented with fixmes:- + High: 1 + Low: 1 +

+ +

Implementation Notes

+ + + + + + + + + +

Step	Notes
1. Make HTTP request	+ + 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. + + + + Fixme (High) + Enable the retrieval of a specific use case rather than all at once. + + + Fixme (Low) + Make the summary optional - there is a switch in the XSL for this, just need to pass a property + from the XMAP + +

Step

Notes

1. Make HTTP request

+ +

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.

+ +
+

Fixme (High)

Enable the retrieval of a specific use case rather than all at once.

Fixme (Low)

Make the summary optional - there is a switch in the XSL for this, just need to pass a property + from the XMAP

+ +

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.

+ +

Summary

+Make HTTP request +

+ +

Details

+ + + + + + + + + +

Step	Description	Result	Status
1. Make HTTP request	+ + + Request + http://localhost:8888/docs/developer/featureMatrix/useCases.xml + + +	+ + + An XDoc is created that lists the steps in each use case and identifies the status + of each use case. + + +	+ + Warning + Not Implemented + + Blockers: 1 +

+ +

Implementation Notes

+ + + + + + + + + +

Step	Notes
1. Make HTTP request	+ + 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, + + + + Fixme (Blocker) + 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. + +

Step

Notes

1. Make HTTP request

+ +

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,

+ +
+

Fixme (Blocker)

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.

+ +

+ + +

+ +

+ + +

About

+Index +

Release Notes

+Version 0.1 +

+Version 0.2-dev +

+Changes +

+Todo +

+Plugins Index +

Documentation

User

+Change Log +

+Use Cases +

+All Cases +

Developer

Change Log

+Use Cases +

+All Cases +

Projects

Navigation Indexes

All

+projectInfo +

+Apache Forrest +

Java

+Apache Forrest +

Language Indexes

+Java +

+XML +

+XSLT +

Page Indexes

+Index by Language +

+Java Index +

+Index by Category +

+ +

+ + +

Font size: + + + +

Use Cases

+Uses Cases for Change Log management features of org.apache.forrest.plugin.input.projectInfo +
- +Write status.xml File +
  - +Justification +
  - +Summary +
  - +Details +
  - +Implementation Notes +
  +
+

+ +

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

Changes between releases
Developers involved in a release
Release notes

+ +

Summary

+Create/open a status.xml file +
+Create a developer list +
+Create a contexts list +
+Create a changes element +
+Create a release element +
+Create a notes element +
+Add actions taken during the development cycle +
+Generate the change log +

+ +

Details

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Description	Result	Status
1. 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.	Implemented
2. 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.	Implemented
3. 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: + + +<contexts> + <context id="code" title="Changes to the Code Base"/> + <context id="docs" title="Changes to Documentation"/> + <context id="admin" title="Changes to Project Administration"/> + <context id="design" title="Changes to Design"/> + <context id="build" title="Changes to Build"/> +</contexts> + + +	The status.xml file describes the sufficient contexts to group common + actions together.	Implemented
4. 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.	Implemented
5. 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.	Implemented
6. 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.	Implemented
7. 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.	Implemented
8. 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.	Implemented

+ +

Implementation Notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step	Notes
1. Create/open a status.xml file	+ +
2. Create a developer list	+ +
3. Create a contexts list	+ +
4. Create a changes element	+ +
5. Create a release element	+ +
6. Create a notes element	+ +
7. Add actions taken during the development cycle	+ +
8. Generate the change log	+ +

+ +