Edgewall Software

Changes between Initial Version and Version 1 of CookBook/Configuration/RequirementsManagement


Ignore:
Timestamp:
Oct 22, 2015, 11:34:19 AM (4 years ago)
Author:
Cinc-th
Comment:

How to use Trac for requirements management.

Legend:

Unmodified
Added
Removed
Modified
  • CookBook/Configuration/RequirementsManagement

    v1 v1  
     1[[PageOutline]]
     2= Requirements Management
     3
     4Every once in a while there is a question about doing requirements management with Trac. For quite some time there is a th:Request-a-Hack for a plugin implementing it, see th:#1226. While having an out of the box solution would be nice there are quite a few plugins which can be leveraged for building a requirements management solution.
     5
     6On this page one possible approach is shown for doing so. I'm working in development of [https://en.wikipedia.org/wiki/IEC_61508 IEC 61508] compliant control devices. We use Trac for doing all the requirements tracking mandated by the aforementioned standard. For a mid-sized project we currently track something like 4000-6000 requirements and testcases.
     7
     8Be aware that the solution presented here may or may not work for you. We use quite some custom made plugins to support our internal processes wrt requirements tracking. These plugins are private and you may have to create your own to scratch your own itch.
     9
     10== Before you start
     11Don't select a tool because it's fancy and then model your requirements management process so it can be supported by the tool. This will fail in the end.
     12
     13Make sure you know your process and environment, e.g.
     14* Which types of requirements do you have? System requirements, functional requirements, test cases, ... ?
     15* Who is writing them? The tech people or maybe management people? You will learn that it may be impossible to drag your mangement people away from MS Word and friends. So you may need a Word document importer.
     16* Is there a predefined workflow for requirements, e.g. ''draft->in review->approved->closed''?
     17* Is the workflow dependent on the type of requirement?
     18* How do you manage changes to requirements?
     19* What about roles and permissions in the process?
     20* Do you need some kind of sign off?
     21* It may be necessary to import data from other tools or departments. For example the test department may be using their own tool chain and even their own bug tracker.
     22* ...
     23
     24After reviewing your process requirements you should evaluate if Trac with the appropriate plugins is a viable solution. Don't do that by counting bullet points but by actually using it for a project. The beauty of Trac is that by adding the right plugin or writing a new one more or less every need may be fulfilled and in the end your solution **exactly** matches your process requirements.
     25
     26== Requirements management using Trac
     27The following sections describe a bare bones implementation for requirements tracking using some available plugins.
     28=== Environment type
     29Each project lives in a separate environment with its own SQLite database. This way you may not accidentally alter data not belonging to your current project because of a misconfiguration (e.g. broken permissions) or bug in one of your plugins. It makes access control easier which may be important.
     30
     31After the project is done one may revoke all write permissions and archive the complete environment so the current state of requirements is frozen.
     32
     33
     34=== Requirement types
     35To distinguish requirements and test cases at least two new ticket types must be created:
     36* {{{requirement}}}
     37* {{{testcase}}}
     38
     39In our department we only track requirements in the environment so all other ticket types are removed. If you want to use your requirements Trac also for issue tracking keep the standard ticket types. There is no need to create special types for each level of a [https://en.wikipedia.org/wiki/V-Model_(software_development) ''V model''] but nobody stops you from doing so.
     40
     41For administrating ticket types go to the ''admin'' area of your Trac installation or use the command line interface.
     42
     43{{{
     44trac-admin /path/to/projenv ticket_type add requirement
     45
     46trac-admin /path/to/projenv ticket_type add testcase
     47}}}
     48
     49TracAdmin describes the command line interface in full length.
     50
     51=== Defining roles
     52It may be necessary to define additional permissions to have more control of the requirements workflow. For example there may be a distinct group for requirements review and approval while the QA department is responsible for closing requirements.
     53
     54To define the additional permissions
     55* {{{REQUIREMENT_APPROVE}}}
     56* {{{REQUIREMENT_CLOSE}}}
     57
     58add the following to your trac.ini:
     59{{{#!ini
     60[components]
     61tracopt.perm.config_perm_provider.ExtraPermissionsProvider = enabled
     62
     63[extra-permissions]
     64REQUIREMENT_ADMIN = REQUIREMENT_APPROVE, REQUIREMENT_CLOSE
     65}}}
     66Note that this also defines the permission {{{REQUIREMENT_ADMIN}}} which grants {{{REQUIREMENT_APPROVE}}} and {{{REQUIREMENT_CLOSE}}}.
     67
     68For more information see ExtraPermissionsProvider.
     69
     70=== Creating specialized workflows
     71A workflow for a requirement is very different from a standard issue workflow. Using th:MultipleWorkflowPlugin (disclaimer: I'm the maintainer) specific workflows for each new type may be created.
     72
     73Add this to your trac.ini:
     74{{{#!ini
     75[components]
     76# Enable MultipleWorkflowPlugin
     77multipleworkflow.* = enabled
     78
     79[ticket-workflow-requirement]
     80# Create special workflow for tickets with type 'requirement'
     81# Note that special permissions are used here
     82leave = * -> *
     83leave.default = 1
     84leave.operations = leave_status
     85
     86approve = new, reopened -> approved
     87approve.operations = del_resolution
     88approve.permissions = REQUIREMENT_APPROVE
     89
     90reopen_verified = closed -> reopened
     91reopen_verified.name = Reopen
     92reopen_verified.operations = set_resolution
     93reopen_verified.set_resolution = from verified
     94reopen_verified.permissions = TICKET_MODIFY
     95
     96reopen_approved = approved -> reopened
     97reopen_approved.name = Reopen
     98reopen_approved.operations = set_resolution
     99reopen_approved.set_resolution = from approved
     100reopen_approved.permissions = TICKET_CREATE
     101
     102remove = new, reopened, approved, closed -> removed
     103remove.name = Remove this Requirement permanently
     104remove.operations = set_resolution
     105remove.set_resolution = removed
     106remove.permissions = TICKET_MODIFY
     107
     108verify = approved -> closed
     109verify.name = Verifiy the Requirement and mark
     110verify.operations = set_resolution
     111verify.set_resolution = verified
     112verify.permissions = REQUIREMENT_CLOSE
     113
     114[ticket-workflow-testcase]
     115leave = * -> *
     116leave.default = 1
     117leave.operations = leave_status
     118...
     119}}}
     120{{{
     121#!Workflow width=800 height=400
     122leave = * -> *
     123leave.default = 1
     124leave.operations = leave_status
     125
     126approve = new, reopened -> approved
     127approve.operations = del_resolution
     128approve.permissions = REQUIREMENT_APPROVE
     129
     130reopen_verified = closed -> reopened
     131reopen_verified.name = Reopen
     132reopen_verified.operations = set_resolution
     133reopen_verified.set_resolution = from verified
     134reopen_verified.permissions = TICKET_MODIFY
     135
     136reopen_approved = approved -> reopened
     137reopen_approved.name = Reopen
     138reopen_approved.operations = set_resolution
     139reopen_approved.set_resolution = from approved
     140reopen_approved.permissions = TICKET_CREATE
     141
     142remove = new, reopened, approved, closed -> removed
     143remove.name = Remove this Requirement permanently
     144remove.operations = set_resolution
     145remove.set_resolution = removed
     146remove.permissions = TICKET_MODIFY
     147
     148verify = approved -> closed
     149verify.name = Verifiy the Requirement and mark
     150verify.operations = set_resolution
     151verify.set_resolution = verified
     152verify.permissions = REQUIREMENT_CLOSE
     153}}}
     154In this workflow special permissions as defined in section [#Definingroles Defining roles] are used to control access. You may leverage the full power of [TracWorkflow TracWorkflow]s here, for example assigning new owners on state change.
     155
     156Using some validation plugin correct values in required ticket fields can be enforced. Have a look at
     157* th:TicketValidatorPlugin
     158* th:TracTicketValidatorPlugin
     159* th:TracTicketConditionalValidatePlugin
     160
     161You have to adapt the given workflow to your own process but you get the idea.
     162
     163=== Parent - child relationship
     164There **must** be some kind of parent - child relationship between tickets so one may follow the chain of requirements in forward and backwards direction. The following plugins are suitable:
     165
     166* th:SubticketsPlugin
     167* th:MasterTicketsPlugin
     168* th:ChildTicketsPlugin (my preferred solution and described here)
     169
     170
     171For requirements tickets th:ChildTicketsPlugin adds buttons to the ticket page to create a child ticket of type {{{requirement}}} or {{{testcase}}}. Any child tickets are directly shown on the ticket page.
     172
     173See th:ChildTicketsPlugin/Examples for some screenshots of the plugin in action.
     174
     175Add the following to your trac.ini to use th:ChildTicketsPlugin:
     176{{{#!ini
     177[childtickets]
     178# Allow child tickets for tickets of type 'requirement'
     179parent.requirement.allow_child_tickets = true
     180# Restrict child ticket types
     181parent.requirement.restrict_child_type = requirement, testcase
     182# Define the table headers to be shown for child tickets
     183parent.requirement.table_headers = summary, type, status, component, description
     184# No child tickets for ticket type 'testcase'
     185parent.testcase.allow_child_tickets = false
     186
     187[components]
     188# Enable ChildTicketsPlugin
     189childtickets.* = enabled
     190childtickets.childtickets.tracchildticketsmodule = enabled
     191
     192[ticket-custom]
     193# Define ticket custom field for use with ChildTicketsPlugin
     194parent = text
     195parent.format = wiki
     196parent.label = Parent ID
     197}}}
     198
     199With the given settings only tickets with type {{{requirement}}} or {{{testcase}}} are allowed as children of requirements tickets. Testcase tickets can't have any children. If you use your environment also for issue tracking it may be necessary to change the configuration to allow other ticket types like {{{defect}}} or {{{task}}} tickets.
     200
     201
     202See the th:ChildTicketsPlugin page for more configuration options.
     203
     204There is a macro th:ChildTicketTreeMacro to show a ticket hierarchy everywhere wiki content is allowed. This may be useful for reporting purposes.
     205
     206=== Requirements grouping
     207Grouping may be achieved by specifying different requirement types. Each level of the ''V model'' is mapped to a different ticket type. This is probably not practical enough because you may have several thousand requirements for a single level.
     208
     209Additional grouping may be done using the {{{component}}} field of a ticket or a custom ticket field. In our environment this is done using the custom field {{{docid}}} because every requirement starts life in an external document with a unique document id which is imported into Trac after approval.
     210
     211For this add the following to your trac.ini:
     212{{{#!ini
     213[ticket-custom]
     214# Define field for grouping of requirements
     215docid = text
     216docid.format = text
     217docid.label = Document ID
     218}}}
     219
     220By grouping it's possible to find requirements belonging to some part of your product/project. For example in hardware development you may group all requirements pertaining to the power supply by one id thus making it easy for the power supply people to check for fullfillment.
     221
     222=== Cleaning up the ticket page
     223Depending on your audience the ticket page may be overwhelming because of all the fields. But there are quite a few plugins to hide unneeded ticket fields or prevent changes.
     224
     225th:CondFieldsGenshiPlugin is one of them and is used here to disallow changing of the ticket type field. It's unlikely a requirement morphs into a testcase so preventing any accidental damage is a good idea.
     226
     227{{{#!ini
     228[components]
     229condfieldsgenshi.* = enabled
     230
     231[condfieldsgenshi]
     232# We only tweak the 'type' filed atm
     233tweaks = type
     234default = enable
     235
     236# Disable ticket type field
     237type.type_cond = requirement, testcase
     238}}}
     239Hide any other ticket fields you don't want your users to see or change.
     240
     241=== Possible improvements
     242As written before this presents a basic solution which may already work for you. You possibly want in addition:
     243
     244* Some reporting. You may use TicketQuery for that or create TracReports.
     245* Sign of for requirements. CookBook/Configuration/SignedTickets may be a starting point.
     246* ...
     247
     248== Summary
     249Install the following plugins:
     250* th:MultipleWorkflowPlugin
     251* th:ChildTicketsPlugin
     252* th:CondFieldsGenshiPlugin
     253
     254Add the following settings to your trac.ini:
     255{{{#!ini
     256[childtickets]
     257# Allow child tickets for tickets of type 'requirement'
     258parent.requirement.allow_child_tickets = true
     259# Restrict child ticket types
     260parent.requirement.restrict_child_type = requirement, testcase
     261# Define the table headers to be shown for child tickets
     262parent.requirement.table_headers = summary, type, status, component, description
     263# No child tickets for ticket type 'testcase'
     264parent.testcase.allow_child_tickets = false
     265
     266[components]
     267# Enable ChildTicketsPlugin
     268childtickets.* = enabled
     269childtickets.childtickets.tracchildticketsmodule = enabled
     270# Enable CondFieldsGenshiPlugin
     271condfieldsgenshi.* = enabled
     272# Enable MultipleWorkflowPlugin
     273multipleworkflow.* = enabled
     274# Remove this if you need no special permissions
     275tracopt.perm.config_perm_provider.ExtraPermissionsProvider = enabled
     276
     277[condfieldsgenshi]
     278# We only tweak the 'type' filed atm
     279tweaks = type
     280default = enable
     281# Disable ticket type field
     282type.type_cond = requirement, testcase
     283
     284# Remove this section if you need no special permissions
     285[extra-permissions]
     286REQUIREMENT_ADMIN = REQUIREMENT_APPROVE, REQUIREMENT_CLOSE
     287
     288[ticket]
     289# Use MultipleWorkflowPlugin for ticket workflows
     290workflow = MultipleWorkflowPlugin
     291
     292[ticket-custom]
     293# Define ticket custom field for use with ChildTicketsPlugin
     294parent = text
     295parent.format = wiki
     296parent.label = Parent ID
     297# Define field for grouping of requirements
     298docid = text
     299docid.format = text
     300docid.label = Document ID
     301
     302[ticket-workflow-requirement]
     303# Create special workflow for tickets with type 'requirement'
     304# Note that special permissions are used here
     305leave = * -> *
     306leave.default = 1
     307leave.operations = leave_status
     308
     309approve = new, reopened -> approved
     310approve.operations = del_resolution
     311approve.permissions = REQUIREMENT_APPROVE
     312
     313reopen_verified = closed -> reopened
     314reopen_verified.name = Reopen
     315reopen_verified.operations = set_resolution
     316reopen_verified.set_resolution = from verified
     317reopen_verified.permissions = TICKET_MODIFY
     318
     319reopen_approved = approved -> reopened
     320reopen_approved.name = Reopen
     321reopen_approved.operations = set_resolution
     322reopen_approved.set_resolution = from approved
     323reopen_approved.permissions = TICKET_CREATE
     324
     325remove = new, reopened, approved, closed -> removed
     326remove.name = Remove this Requirement permanently
     327remove.operations = set_resolution
     328remove.set_resolution = removed
     329remove.permissions = TICKET_MODIFY
     330
     331verify = approved -> closed
     332verify.name = Verifiy the Requirement and mark
     333verify.operations = set_resolution
     334verify.set_resolution = verified
     335verify.permissions = REQUIREMENT_CLOSE
     336
     337# Create your testcase workflow here
     338[ticket-workflow-testcase]
     339leave = * -> *
     340leave.default = 1
     341leave.operations = leave_status
     342...
     343}}}
     344
     345On the command line enter the following commands to add ticket types:
     346
     347{{{
     348trac-admin /path/to/projenv ticket_type add requirement
     349
     350trac-admin /path/to/projenv ticket_type add testcase
     351}}}