view release on metacpan or  search on metacpan

lib/App/Requirement/Arch.pm  view on Meta::CPAN

Goals:

	- keep things as simple if possible
	- Adapt to the requirement process you use and propose one if you don't have any
	- the UI is provided by your platform
	- power users like the command line
	- handle small to middle sized projects ( wich are the most common)
	- try to make it appealing to developers

The set of applications should be usable by anyone but having a development background does help. If the people writing  requirements
have little or no knowledge of requirements handling, someone with the knowledge should help them. This is true for any requirement 
gathering process wether they use this application or a multi million dollar commercial framework.

=head1 DOCUMENTATION

=head2 Physical representation of the requirements:

=head2 Decisions

	- Each requirements are gathered in a text file
	- The Requirement must match a specified format
	- The format is Perl
	- The format requires the presence of specific fields
	- The requirements can be gathered from multiple places

=head3 Consequences:

	- gathering requirement is simple (except if your product manager has problems opening files with unix line ending (no this is not a joke))
	- tools to verify the format of the requirements are easilly written

=head3 Positive side effects:

	- requirements can be shared between projects, simply gather them from multiple projects
	- the physical organisation of the file is left to user, have any directory structure you deem good
	- requirements can be under version control and you can choose whatever system you like
	- you can use the tools you are used to (this was listed above as a goal)
		- your favorit text editor
		- your favorit version control system
		- your favorit explorer (konqueror, lynx, mc, tree, ...)
		- your favorit text manipulation commands (grep, sort, ...)

=head2 Requirement handling activities

Below is a non exhaustive list of the activities that compose requirement handling:

	Creation
	Format Verification
	Breakdown
	Merging
	Categorisation
	Review
	Filtering
	Visualisation

=head2 Requirement format

The requirement format is defined in I<master_template.pl>. The template is used to create new requirements and check existing templates. 
I<master_template.pl> also contains the definition of a use case template. It is possible to modify and expand I<master_template.pl> with 
more type or different fields for a type. The discussion below is not about the individual fields but their format, see L<Default template fields>.

for the REQUIREMENT type the template looks like:

		{
		UUID => {TYPE =>$SCALAR, DEFAULT => undef},
		TYPE => {TYPE =>$SCALAR, DEFAULT => 'requirement', ACCEPTED_VALUES => ['use case', 'requirement']},
		ABSTRACTION_LEVEL => {TYPE =>$SCALAR, DEFAULT => 'system', ACCEPTED_VALUES => ['architecture', 'system', 'module', 'none'], OPTIONAL => 1},

		ORIGINS => {TYPE =>$ARRAY, DEFAULT => []} ,
		CREATORS => {TYPE =>$ARRAY, DEFAULT => []},

		CATEGORIES => {TYPE =>$ARRAY, DEFAULT => []},
		NAME => {TYPE =>$SCALAR, DEFAULT =>''} ,
		...
		},

Each field has a 

	TYPE:  $SCALAR or $ARRAY
	DEFAULT: a default value
	ACCEPTED_VALUES: values that are used to verify the contents of the fiels
	OPTIONAL: wether the field is optional or not. I prefer always having all the fields but other user may prefer not seeing them. Unecessary fields
		are ugly (but the whole buisiness is rather unxxx). the disadvantages of not seing all the fields is that the user has to know what she can
		write or not which, IMO, makes it more difficult
		
TODO: add a comment entry in each field so it can be displayed as help to the user	

=head3 Verification

Once you have created your requirement you can check it's validity with tthe B<ra_check> application. You can check multiple requirement
simulteanously.

B<ra_check> will report the following

=head4 Format error

The syntax you used is not valid. This happends if you forget a comma or have unbalanced braces, ...

=head4 Errorneous  fields

A fields contains data that are not allowed by the template

=head4 Missing  Fields

A non-optional fiels is missing from the requirement

=head4 Extra Fields

A field that was not defined in the requirement template was found. This will only generate a warning because we feel that you should be able to add a field
to a requirement without having to change the template for the following reasons:

	- you may not not have the rights needed to change the template
	- you may want to discuss it with colleagues first
	- you need the extra field right now for something you deem important but you can't be bothered by silly administrative tasks

=head3 Default template fields

=head4 Example:

	{
	UUID => undef ,
	TYPE => 'requirement',