view release on metacpan or  search on metacpan

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

#-------------------------------------------------------------------------------

use English qw( -no_match_vars ) ;

use Readonly ;
Readonly my $EMPTY_STRING => q{} ;

use Carp qw(carp croak confess) ;

#-------------------------------------------------------------------------------

=head1 NAME

App::Requirement::Arch - Easy requirements creation and handling

=head1 SYNOPSIS

	$> ra_new my_requirement
	$> edit my_requirement
	$> git add my_requirement (if you want to keep your requirements under version control)
	$> ra_show

=head1 BACKGROUND

This module is the result of discussions I have had with friends and collegues. Kolbjörn Gripner, Johan Nat och Dag and Cristian Pendelton 
(to name a few) and I have had heated discussions about how important requirements are and how they should be handled. One common 
trait we share is that we believe requirements are very important and demand a lot of serious work. The reward is great put the effort to 
be put into requirement gathering, prioritizing, categorizing, reviewing, following down to testing is an activity seen as a burden by too many.

By far the greatest challenge to good requirement, and thus to the production of professional application or service, is cultural. Product 
manager are known to range from bad to very bad when it comes to requirement handling, with the too seldom seen exception, producing
low utility excel sheets that developers can't make sense of or that are lacking the minimum information to be of any use.

Developers, particularely in the open source community, are not much better. Their requirement handling ranging from unexistant to
simplistic (todos, error DBs, ...). Here too, development culture and resistance to change is the problem.

We believe we need a system to make requirement handling more attractive so people are 'happy' to work with requirement.

Multidimensional_Requirement_Database.pod, a document writen by Kolbjörn, is an interresting read wich shows what goes on into the 
head of someone who is deeply involved with requirement gathering. Although the format is dry, it is an excellent analysis  of what a better
requirement handling process and tools should handle.

This application set was developed in an agile, ad-hoc , way and it could itself have had great use of a simple requirement handling tool set.
IT has been used in a project with 4 people, hundreds of requirements and months of requirement gathering. Of course there is still a lot of 
work to do (but one of the goals is to not over do it) and your help and input is wished for.

=head1 DESCRIPTION

This module implements  a set of application that you can use to do easy requirement handling. We have defined
a few goals to help us make the requirement handling 'easy' while keeping it powerfull and keeping us out of your way.

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 => []},