Edgewall Software

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


Ignore:
Timestamp:
Dec 8, 2015, 6:30:30 PM (4 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • CookBook/Configuration/RequirementsManagement

    v1 v2  
    1 [[PageOutline]]
     1[[PageOutline(2-5,Contents,pullout)]]
     2
    23= Requirements Management
    34
    4 Every 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 
    6 On 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 
    8 Be 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.
     5Every once in a while there is a question about whether Trac supports [wikipedia:Requirements_management requirements management]. There is even a plugin request for this, see th:#1226. While having an out of the box solution would be nice, there are a few plugins already available which can be used for building a requirements management solution.
     6
     7On this page one possible approach is shown for doing so. I'm working in development of [wikipedia:IEC_61508 IEC 61508] compliant control devices. We use Trac for tracking all the requirements mandated by this standard, currently something like 4000-6000 requirements and test cases.
     8
     9The solution presented here may or may not work for you. We use quite some custom made plugins to support our internal processes. These plugins are private and you may have to create your own.
     10
     11See also: th:ProjectManagementIdeas
    912
    1013== Before you start
    11 Don'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 
    13 Make 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 
    24 After 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.
     14
     15Don't select a tool because it's fancy and then organise your requirements management process so it can be supported by the tool. This will fail in the end.
     16
     17Make sure you know your process and environment:
     18 * Which types of requirements do you have? System requirements, functional requirements, test cases, performance requirements?
     19 * Who owns them? There may be more than one stakeholder in the project and each stakeholder has the responsibility to understand and prioritise their own requirements.
     20 * Who is writing them? The tech people or maybe management people? It may be impossible to drag your management people away from MS-Word c.s., so you may need a Word document importer.
     21 * Is there a predefined workflow for requirements, eg {{{ draft -> in review -> approved -> closed }}}?
     22 * Is the workflow dependent on the type of requirement?
     23 * How do you manage changes to requirements?
     24 * What about roles and permissions in the process?
     25 * Do you need some kind of sign off?
     26 * It may be necessary to import data from other tools or departments. For example the test department may be using their own tooling and even their own bug tracker.
     27
     28After 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.
    2529
    2630== Requirements management using Trac
    27 The following sections describe a bare bones implementation for requirements tracking using some available plugins.
     31
     32The following sections describe a bare bones implementation for requirements management using some available Trac plugins.
     33
    2834=== Environment type
     35
    2936Each 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.
    3037
    3138After the project is done one may revoke all write permissions and archive the complete environment so the current state of requirements is frozen.
    3239
    33 
    3440=== Requirement types
     41
    3542To distinguish requirements and test cases at least two new ticket types must be created:
    36 * {{{requirement}}}
    37 * {{{testcase}}}
    38 
    39 In 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 
    41 For administrating ticket types go to the ''admin'' area of your Trac installation or use the command line interface.
    42 
    43 {{{
    44 trac-admin /path/to/projenv ticket_type add requirement
    45 
    46 trac-admin /path/to/projenv ticket_type add testcase
     43 * {{{requirement}}}
     44 * {{{testcase}}}
     45
     46In 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 [wikipedia:V-Model_(software_development) '''V model'''], but nobody stops you from doing so.
     47
     48For administrating ticket types go to the '''Admin''' area of your Trac installation or use the command line:
     49{{{#!sh
     50$ trac-admin /path/to/projenv ticket_type add requirement
     51$ trac-admin /path/to/projenv ticket_type add testcase
    4752}}}
    4853
     
    5055
    5156=== Defining roles
     57
    5258It 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.
    5359
    54 To define the additional permissions
    55 * {{{REQUIREMENT_APPROVE}}}
    56 * {{{REQUIREMENT_CLOSE}}}
    57 
    58 add the following to your trac.ini:
     60To define the additional permissions:
     61 * {{{REQUIREMENT_APPROVE}}}
     62 * {{{REQUIREMENT_CLOSE}}}
     63
     64add the following to your `trac.ini` file:
    5965{{{#!ini
    6066[components]
     
    6470REQUIREMENT_ADMIN = REQUIREMENT_APPROVE, REQUIREMENT_CLOSE
    6571}}}
    66 Note that this also defines the permission {{{REQUIREMENT_ADMIN}}} which grants {{{REQUIREMENT_APPROVE}}} and {{{REQUIREMENT_CLOSE}}}.
     72
     73Note that this also defines the permission {{{REQUIREMENT_ADMIN}}}, which grants {{{REQUIREMENT_APPROVE}}} and {{{REQUIREMENT_CLOSE}}}.
    6774
    6875For more information see ExtraPermissionsProvider.
    6976
    7077=== Creating specialized workflows
    71 A 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 
    73 Add this to your trac.ini:
     78
     79A workflow for a requirement is very different from a standard issue workflow. Using th:MultipleWorkflowPlugin (disclosure: I'm the maintainer) specific workflows for each new type may be created.
     80
     81Add this to your `trac.ini` file:
    7482{{{#!ini
    7583[components]
     
    107115
    108116verify = approved -> closed
    109 verify.name = Verifiy the Requirement and mark
     117verify.name = Verify the Requirement and mark
    110118verify.operations = set_resolution
    111119verify.set_resolution = verified
     
    118126...
    119127}}}
     128
     129This results in the following control flow:
    120130{{{
    121131#!Workflow width=800 height=400
     
    147157
    148158verify = approved -> closed
    149 verify.name = Verifiy the Requirement and mark
     159verify.name = Verify the Requirement and mark
    150160verify.operations = set_resolution
    151161verify.set_resolution = verified
    152162verify.permissions = REQUIREMENT_CLOSE
    153163}}}
    154 In 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 
    156 Using 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
     164
     165In this workflow special permissions as defined in section [#Definingroles Defining roles] are used to control access. You may use the full power of [TracWorkflow TracWorkflow]s here, for example assigning new owners on state change.
     166
     167Using one of the following validation plugins, correct values in required ticket fields can be enforced:
     168 * th:TicketValidatorPlugin
     169 * th:TracTicketValidatorPlugin
     170 * th:TracTicketConditionalValidatePlugin
    160171
    161172You have to adapt the given workflow to your own process but you get the idea.
    162173
    163 === Parent - child relationship
    164 There **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 
    171 For 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.
     174=== Parent - child relationships
     175
     176There **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 can be used for this:
     177
     178 * th:SubticketsPlugin
     179 * th:MasterTicketsPlugin
     180 * th:ChildTicketsPlugin (my preferred solution and described here)
     181
     182For requirements tickets the 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.
    172183
    173184See th:ChildTicketsPlugin/Examples for some screenshots of the plugin in action.
    174185
    175 Add the following to your trac.ini to use th:ChildTicketsPlugin:
     186Add the following to your `trac.ini` file to use th:ChildTicketsPlugin:
    176187{{{#!ini
    177188[childtickets]
     
    199210With 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.
    200211
    201 
    202212See the th:ChildTicketsPlugin page for more configuration options.
    203213
    204 There is a macro th:ChildTicketTreeMacro to show a ticket hierarchy everywhere wiki content is allowed. This may be useful for reporting purposes.
     214There is a macro th:ChildTicketTreeMacro to show a ticket hierarchy everywhere where wiki content is allowed. This may be useful for reporting purposes.
    205215
    206216=== Requirements grouping
    207 Grouping 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 
    209 Additional 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 
    211 For this add the following to your trac.ini:
     217
     218Grouping 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 when you have several thousand requirements for a single level.
     219
     220Additional 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.
     221
     222For this add the following to your `trac.ini` file:
    212223{{{#!ini
    213224[ticket-custom]
     
    218229}}}
    219230
    220 By 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.
     231By 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.
    221232
    222233=== Cleaning up the ticket page
    223 Depending 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 
    225 th: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.
     234
     235Depending 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.
     236
     237th:CondFieldsGenshiPlugin is one of them and is used here to disallow changing the ticket type field. It's unlikely that a requirement morphs into a test case, so preventing any accidental damage is a good idea.
    226238
    227239{{{#!ini
     
    237249type.type_cond = requirement, testcase
    238250}}}
     251
    239252Hide any other ticket fields you don't want your users to see or change.
    240253
    241254=== Possible improvements
    242 As 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 * ...
     255
     256What is described here is a basic solution which may already work for you. You possibly want in addition:
     257
     258* Some reporting: use TicketQuery for that or create TracReports.
     259* Sign off for requirements: CookBook/Configuration/SignedTickets may be a starting point.
    247260
    248261== Summary
     262
    249263Install the following plugins:
    250 * th:MultipleWorkflowPlugin
    251 * th:ChildTicketsPlugin
    252 * th:CondFieldsGenshiPlugin
    253 
    254 Add the following settings to your trac.ini:
     264 * th:MultipleWorkflowPlugin
     265 * th:ChildTicketsPlugin
     266 * th:CondFieldsGenshiPlugin
     267
     268Add the following settings to your `trac.ini` file:
    255269{{{#!ini
    256270[childtickets]
     
    330344
    331345verify = approved -> closed
    332 verify.name = Verifiy the Requirement and mark
     346verify.name = Verify the Requirement and mark
    333347verify.operations = set_resolution
    334348verify.set_resolution = verified
     
    345359On the command line enter the following commands to add ticket types:
    346360
    347 {{{
    348 trac-admin /path/to/projenv ticket_type add requirement
    349 
    350 trac-admin /path/to/projenv ticket_type add testcase
    351 }}}
     361{{{#!sh
     362$ trac-admin /path/to/projenv ticket_type add requirement
     363$ trac-admin /path/to/projenv ticket_type add testcase
     364}}}