[[PageOutline(2-5,Contents,pullout)]] = Requirements Management Every 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. On 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. The 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. See also: th:ProjectManagementIdeas == Before you start Don'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. Make sure you know your process and environment: * Which types of requirements do you have? System requirements, functional requirements, test cases, performance requirements? * 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. * 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. * Is there a predefined workflow for requirements, eg {{{ draft -> in review -> approved -> closed }}}? * Is the workflow dependent on the type of requirement? * How do you manage changes to requirements? * What about roles and permissions in the process? * Do you need some kind of sign off? * 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. 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. == Requirements management using Trac The following sections describe a bare bones implementation for requirements management using some available Trac plugins. === Environment type Each 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. After the project is done one may revoke all write permissions and archive the complete environment so the current state of requirements is frozen. === Requirement types To distinguish requirements and test cases at least two new ticket types must be created: * {{{requirement}}} * {{{testcase}}} 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 [wikipedia:V-Model_(software_development) '''V model'''], but nobody stops you from doing so. For administrating ticket types go to the '''Admin''' area of your Trac installation or use the command line: {{{#!sh $ trac-admin /path/to/projenv ticket_type add requirement $ trac-admin /path/to/projenv ticket_type add testcase }}} TracAdmin describes the command line interface in full length. === Defining roles It 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. To define the additional permissions: * {{{REQUIREMENT_APPROVE}}} * {{{REQUIREMENT_CLOSE}}} add the following to your `trac.ini` file: {{{#!ini [components] tracopt.perm.config_perm_provider.ExtraPermissionsProvider = enabled [extra-permissions] REQUIREMENT_ADMIN = REQUIREMENT_APPROVE, REQUIREMENT_CLOSE }}} Note that this also defines the permission {{{REQUIREMENT_ADMIN}}}, which grants {{{REQUIREMENT_APPROVE}}} and {{{REQUIREMENT_CLOSE}}}. For more information see ExtraPermissionsProvider. === Creating specialized workflows A 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. Add this to your `trac.ini` file: {{{#!ini [components] # Enable MultipleWorkflowPlugin multipleworkflow.* = enabled [ticket-workflow-requirement] # Create special workflow for tickets with type 'requirement' # Note that special permissions are used here leave = * -> * leave.default = 1 leave.operations = leave_status approve = new, reopened -> approved approve.operations = del_resolution approve.permissions = REQUIREMENT_APPROVE reopen_verified = closed -> reopened reopen_verified.name = Reopen reopen_verified.operations = set_resolution reopen_verified.set_resolution = from verified reopen_verified.permissions = TICKET_MODIFY reopen_approved = approved -> reopened reopen_approved.name = Reopen reopen_approved.operations = set_resolution reopen_approved.set_resolution = from approved reopen_approved.permissions = TICKET_CREATE remove = new, reopened, approved, closed -> removed remove.name = Remove this Requirement permanently remove.operations = set_resolution remove.set_resolution = removed remove.permissions = TICKET_MODIFY verify = approved -> closed verify.name = Verify the Requirement and mark verify.operations = set_resolution verify.set_resolution = verified verify.permissions = REQUIREMENT_CLOSE [ticket-workflow-testcase] leave = * -> * leave.default = 1 leave.operations = leave_status ... }}} This results in the following control flow: {{{ #!Workflow width=800 height=400 leave = * -> * leave.default = 1 leave.operations = leave_status approve = new, reopened -> approved approve.operations = del_resolution approve.permissions = REQUIREMENT_APPROVE reopen_verified = closed -> reopened reopen_verified.name = Reopen reopen_verified.operations = set_resolution reopen_verified.set_resolution = from verified reopen_verified.permissions = TICKET_MODIFY reopen_approved = approved -> reopened reopen_approved.name = Reopen reopen_approved.operations = set_resolution reopen_approved.set_resolution = from approved reopen_approved.permissions = TICKET_CREATE remove = new, reopened, approved, closed -> removed remove.name = Remove this Requirement permanently remove.operations = set_resolution remove.set_resolution = removed remove.permissions = TICKET_MODIFY verify = approved -> closed verify.name = Verify the Requirement and mark verify.operations = set_resolution verify.set_resolution = verified verify.permissions = REQUIREMENT_CLOSE }}} In 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. Using one of the following validation plugins, correct values in required ticket fields can be enforced: * th:TicketValidatorPlugin * th:TracTicketValidatorPlugin * th:TracTicketConditionalValidatePlugin You have to adapt the given workflow to your own process but you get the idea. === Parent - child relationships 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 can be used for this: * th:SubticketsPlugin * th:MasterTicketsPlugin * th:ChildTicketsPlugin (my preferred solution and described here) For 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. See th:ChildTicketsPlugin/Examples for some screenshots of the plugin in action. Add the following to your `trac.ini` file to use th:ChildTicketsPlugin: {{{#!ini [childtickets] # Allow child tickets for tickets of type 'requirement' parent.requirement.allow_child_tickets = true # Restrict child ticket types parent.requirement.restrict_child_type = requirement, testcase # Define the table headers to be shown for child tickets parent.requirement.table_headers = summary, type, status, component, description # No child tickets for ticket type 'testcase' parent.testcase.allow_child_tickets = false [components] # Enable ChildTicketsPlugin childtickets.* = enabled childtickets.childtickets.tracchildticketsmodule = enabled [ticket-custom] # Define ticket custom field for use with ChildTicketsPlugin parent = text parent.format = wiki parent.label = Parent ID }}} With 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. See the th:ChildTicketsPlugin page for more configuration options. There is a macro th:ChildTicketTreeMacro to show a ticket hierarchy everywhere where wiki content is allowed. This may be useful for reporting purposes. === Requirements grouping 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 when you have several thousand requirements for a single level. 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. For this add the following to your `trac.ini` file: {{{#!ini [ticket-custom] # Define field for grouping of requirements docid = text docid.format = text docid.label = Document ID }}} 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. === Cleaning up the ticket page 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. th: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. {{{#!ini [components] condfieldsgenshi.* = enabled [condfieldsgenshi] # We only tweak the 'type' filed atm tweaks = type default = enable # Disable ticket type field type.type_cond = requirement, testcase }}} Hide any other ticket fields you don't want your users to see or change. === Possible improvements What is described here is a basic solution which may already work for you. You possibly want in addition: * Some reporting: use TicketQuery for that or create TracReports. * Sign off for requirements: CookBook/Configuration/SignedTickets may be a starting point. == Summary Install the following plugins: * th:MultipleWorkflowPlugin * th:ChildTicketsPlugin * th:CondFieldsGenshiPlugin Add the following settings to your `trac.ini` file: {{{#!ini [childtickets] # Allow child tickets for tickets of type 'requirement' parent.requirement.allow_child_tickets = true # Restrict child ticket types parent.requirement.restrict_child_type = requirement, testcase # Define the table headers to be shown for child tickets parent.requirement.table_headers = summary, type, status, component, description # No child tickets for ticket type 'testcase' parent.testcase.allow_child_tickets = false [components] # Enable ChildTicketsPlugin childtickets.* = enabled childtickets.childtickets.tracchildticketsmodule = enabled # Enable CondFieldsGenshiPlugin condfieldsgenshi.* = enabled # Enable MultipleWorkflowPlugin multipleworkflow.* = enabled # Remove this if you need no special permissions tracopt.perm.config_perm_provider.ExtraPermissionsProvider = enabled [condfieldsgenshi] # We only tweak the 'type' filed atm tweaks = type default = enable # Disable ticket type field type.type_cond = requirement, testcase # Remove this section if you need no special permissions [extra-permissions] REQUIREMENT_ADMIN = REQUIREMENT_APPROVE, REQUIREMENT_CLOSE [ticket] # Use MultipleWorkflowPlugin for ticket workflows workflow = MultipleWorkflowPlugin [ticket-custom] # Define ticket custom field for use with ChildTicketsPlugin parent = text parent.format = wiki parent.label = Parent ID # Define field for grouping of requirements docid = text docid.format = text docid.label = Document ID [ticket-workflow-requirement] # Create special workflow for tickets with type 'requirement' # Note that special permissions are used here leave = * -> * leave.default = 1 leave.operations = leave_status approve = new, reopened -> approved approve.operations = del_resolution approve.permissions = REQUIREMENT_APPROVE reopen_verified = closed -> reopened reopen_verified.name = Reopen reopen_verified.operations = set_resolution reopen_verified.set_resolution = from verified reopen_verified.permissions = TICKET_MODIFY reopen_approved = approved -> reopened reopen_approved.name = Reopen reopen_approved.operations = set_resolution reopen_approved.set_resolution = from approved reopen_approved.permissions = TICKET_CREATE remove = new, reopened, approved, closed -> removed remove.name = Remove this Requirement permanently remove.operations = set_resolution remove.set_resolution = removed remove.permissions = TICKET_MODIFY verify = approved -> closed verify.name = Verify the Requirement and mark verify.operations = set_resolution verify.set_resolution = verified verify.permissions = REQUIREMENT_CLOSE # Create your testcase workflow here [ticket-workflow-testcase] leave = * -> * leave.default = 1 leave.operations = leave_status ... }}} On the command line enter the following commands to add ticket types: {{{#!sh $ trac-admin /path/to/projenv ticket_type add requirement $ trac-admin /path/to/projenv ticket_type add testcase }}}