Requirements Specification for Artifact Tracking System

Transcription

1 Requirements Specification for Artifact Tracking System Customer: Avain Technologies represented by Petteri Sulonen Contractor: Artifacts team Michał Pilawski Xiang Liu Jie Chen Jing Lei Kari Saikkonen Wei Yan

2 1. Purpose of the document This document describes Avaintec s requirements for an artifact tracking system for its development process. It is preliminary in nature and is expected to evolve during development. The intended audience of this document is described in table 1. Table 1: Intended audience of this document Group of the readers Reasons for reading Users and customers To give elicit explanation of the requirements that form a base for the software product. Project team 1. To give understanding of functions and properties the system must contain. 2. To create a reference point for testing. 3. To form a base for other documents, i.e. project plan, progress documentation, manuals and other documents 4. To encourage and together with project plan create a base for progress tracking. Internal use 2

3 2. Business goals The system will become a support tool in software project management. It will combine functionalities of other programs and spreadsheets commonly used at Avain Technologies: effort tracking systems (spreadsheet), bug management (Bugzilla) and test reports management (Mandatezilla). It will allow easy follow-up of the project at any of the project levels (from business release phases at the top to single tasks at the bottom) and any of the process life-cycle phases. System built for Avain Technologies will support Four Cycles of Control model presented in Rautiainen et al. (2002). However, usage of the system is not limited to 4CC process. The system skeleton will support changes to its building bricks, cyclists. After changes to those cyclists system will be capable of supporting any other SW development processes. The product will not offer all functionalities of systems like Bugzilla or Mandatezilla. It will allow for only basic operations (for details look point 7). However, it will be designed for further development, thus allowing new functionalities to be added in the future. The customer describes the system-to-be-produced in the following way: The system will be used to track artifacts created by the development process in use at Avaintec, including, but not necessarily limited to, Sprint Backlog Items, Release Backlog Items, Bug Reports, and Session Mandates. Each artifact is associated with an owner or several owners, such as developers, customers, projects, products, and modules. It should be possible to track the status of each of the artifacts, as well as the estimated and actual effort expended in the work associated with them. There are several reasons why the customer needs the system. However, the most essential need of the client is to use functionalities, which are now dispersed among different products, in one system. Product will not only put different functionalities into a single system, but also will help managing interactions between now separately handled objects, thus offering additional reporting and control possibilities. Internal use 3

4 3. Main domain concepts The system will be based on XML objects called cyclists. The core of the system will be built to support different types of cyclists, not only the ones that will be created for Avaintec version of the system. This will be possible through modification of XML files. Cyclists are representatives of concepts that form a basis of SW development process. In case of the system built for Avaintec cyclists types will represent concepts typical to 4CC process (Rautiainen 2002). Textual definitions of the most important terms are presented in Table 2. Graph 1 presents relationships between concepts described in the table. Table 2. Main concepts of the users Concept Description Cyclist General name for all XML based artifacts that form a base of the system. PBL item Product Backlog item is a cyclist representing top-level parts (typically around a year or two long) of the project (product-level activities) RBL item Release Backlog item is a cyclist representing mid-level parts (at the moment four months long but customer aims to change it to three months long) of the project (development-level activities) SBL item Sprint Backlog item is a cyclist representing bottom-level parts (typically four weeks long) of the project. It consists of single tasks. Bug Bug Report is a cyclist representing a bug and its life-cycle. Report Test Test mandate is a cyclist representing different test mandates. Mandate Customer It is an object (not a cyclist) representing customer(s) of each product that rep. the system will help manage. Product It is an object (not a cyclist) representing a general attributes of the rep. managed product. Developer It is an object (not a cyclist) representing each of the developers that take rep. part in the project that the system helps to manage. Internal use 4

5 Graph 1: Generic AvainTec Project Graph 1 presents generic view on AvainTec s projects. Colorful horizontal blocks represent tasks, typically short set of activities that are building bricks of the project. Those tasks form sprints, which are four weeks long (represented by thin vertical black lines). Release cycles are represented by thin black vertical lines (each will consist of three sprints in the developed AvainTec s SW development process). And finally Product (strategic level) phase takes as much as it is needed to deliver the product to customer and consist of any number of release phases. In Avaintec development starts from the top (Vanhanen et al., 2003). First, the product vision is expressed as a Product Backlog (PBL) and an idea pool. The PBL contains a prioritized list of requirements to be implemented. Effort required to fulfill each of the requirements is estimated at the beginning of a release cycle. Then, requirements are prioritized and Release Backlog is created. Requirements are divided into the task on the Sprint level, those task form Sprint Backlog. Thus, each single task can be traced at any time up to the product requirements. In the AvainTec s version of the system five general cyclists will be created. These are described already PBL, RBL and SBL items for each circle of control, Bug Report for bugs and Test Mandate for test mandates. Each of those artifacts instances has its own life-cycle, starting from the time it is born (e.g. requirement is set, bug discovered), through the set of tasks which has to be performed for the artifact to be brought to the end of the life-cycle (e.g. requirement fulfilled, bug fixed). Thus each of those artifacts instances consists of the number of tasks. Those tasks have their owners, people performing them, as well as other characteristics (e.g. estimated time needed to accomplish, real time needed to accomplish). In addition PBLs have their products and customer object (customer of the product). Relationship between these objects is described on the graph 2. Internal use 5

6 Graph 2: Relationship between artifacts in system for Avaintec s 4CC process Internal use 6

7 4. System overview The role of the system is to support SW project management, by providing effort tracking, bug management and test mandates management support. The system will be tailored to Avaintec development process. However, it will be possible to quickly tailor it to any other process through modification of XML files. In its basic form the system will allow its user to create, modify and close instances of different artifacts. It will store and allow for updates of effort estimated and spent on completing tasks. This information will be used in project progress tracking. In addition, system will enable generation of user-specific, release-specific and product-specific reports for internal/managerial purposes as well as for external purposes (on customer demand). Main functions of the system are presented on graph 3. Internal use 7

8 Graph 3: The users and main functions of the system Internal use 8

9 5. User groups The system will be in general used by small (up to 10 people) development teams that use agile development. This particular version will be designed to support teams that use Four Cycles of Control process methodology in their projects. However, the system can be easily reconfigured to support other SW development processes. We can identify two groups of directs users of the system 002 which are project managers and SW developers. Indirectly system will be used in addition by SW product customers. Those three groups and their needs are described in the table 3. Table 3: System users and their needs Users Needs SW developer Software developer plays technical role within development team. He has following needs fulfilled by the product: Need to inform other developers about status of tasks, bugs etc. on which he has worked Need to be informed about status of tasks, bugs etc. on which other developers are working Need to easily report his effort and status of his work to project work Need to have an understanding of a project progress Internal use 9

10 Project manager Project manager is a person responsible for business and administrating activities within the project. The system fulfills his following needs: Need to be informed about work progress of different developers Need to know work effort of developers Need to know status of different tasks, sprints, releases and finally product status Customer Customer is a private-person or company representative that acts on the behalf of future users of the product created by the team consisting of project manager and SW developers. The system fulfills following his needs: Need to know how many hours have been spent on project by developers Need to know how many hours have been spent on different tasks of the project (TEKES) Internal use 10

11 6. User requirements This section shortly describes product use cases. Use case: Work Reporting Id: 001 Summary: SW developer worked on completing particular task. He wants to report his hours to the managers and human resources. Actors: Developer Preconditions: SW developer worked on a task for particular amount of hours. He wants to report his work hours now to manager and human resources. Basic Sequence: Step1: SW developer have finished some continuous period of work (e.g. end of working-day, finished task). Step 2: SW developer opens the system. He selects project for which the work was done. Step 3: Developer selects existent task within the project for modifying. Step 4: He fills hours spent on the task, as well as own estimation of a number of hours still needed to finish the task. Step 5: Developer closes the system. Exceptions: Exception 1: Developer wants to fill in hours spent on work not related to any existent project (e.g. administrative work, general work, sick leave). In that case, depending on the company policy, person authorized has to create PBL object that would represent all activities related to that work e.g. PBL sick-leave. Exception 2: If the task that developer is working on is not in the system while developer approaches step 3, he creates new artifact iteration new task representation. Exception 3: In step 4 if developer has already finished the task he sets it as closed, instead of filling estimation of work needed. Post conditions: System contains updated information on the work done by particular employee. Use case: Managing bugs and test mandates Id: 002 Internal use 11

12 Summary: New bug have been discovered or tests for some new functionality or system are created. Artifact instances representing these bugs or tests are created in the system. Those bug reports or test mandates are modified while different tasks related to those bugs or tests are accomplished. When life-cycle of these bugs or tests gets to an end artifact instances are marked as closed. This helps all developers and project manager track life-cycle of these items. Actors: SW Developers, project manager Preconditions: New bug have been discovered or tests for some new functionality or system are created. Basic Sequence: Step 1: SW developer opens the system. He selects project on which he is working. Step 2: He creates artifact instance that would represent in the system newly discovered bug or created tests for new functionality, module, or system. Step 3: When any task that is related to the bug is accomplished, SW developer opens the system and updates the state of the artifact (e.g. SW developer tested if the bug reported by other developer is really a bug, depending on his findings he changes the life-cycle of the bug from new to verified or closes the object if it was not a real bug). Step 4: SW developer who did the last task in the artifact lifecycle opens the system and closes artifact instance. Exceptions: No exceptions identified at this stage. Post conditions: At any stage of the item life-cycle all developers and project manager have clear source information about the current state of the project and all tasks related to the project that was already accomplished. Use case: Tracking progress Id: 003 Summary: This use case in its form is similar to use case one. SW developer finished a task and he wants reports that. Thanks to this all other developers, as well as project manager can track the progress. Actors: SW developers, project manager Preconditions: PBL is created and products functionalities are prioritized by customer. Task to be done during next iteration are defined. Basic Sequence: Internal use 12

13 Step 1: Person responsible for a task with Sprint or a larger activity e.g. within release opens the system and chooses appropriate project Step 2: He creates new SBLitem, RBLitem or PBLitem depending on the type of activity that will be inputted. Step 3: While the work on the particular item progresses, item status is changed by the developers or managers in parallel with work progress. Step 4: When the task is finished developer closes the task in the system. Exceptions: Results of tests require that the task would be done again. Task is not reopened, but new artifact iteration is created and relationship to previous task is explicitly visible in its name. Post conditions: The system provides information on completed tasks, progress within already started tasks and new tasks that have to be done within iteration. Information includes time already spent on the task and estimated time that still has to be done to accomplish tasks. Use case: Invoice report. Id: 004 Summary: Accounting department is preparing invoice for one of customers. They need to know amount of work done for customer since he was invoiced last time. When work is invoiced the system marks hours as invoiced to avoid charging customer twice for the same work. Actors: Project manager (or any other person preparing the invoice). Preconditions: Certain amount of work has been done for particular customer and hours have been entered to the system by developers. Basic sequence: Step 1: Project manager enters the system and selects type of report. Step 2: Project manager selects customer who will be invoiced and projects for which it is invoiced. Step 3: System opens report page where effort done, but not invoiced is selected. Step 4: Project manager marks activities for which it will invoice the client. These activities are marked in the system as invoiced (invoice date is added to the system). Internal use 13

14 Step 5: Project manager calculates total cost for the customer and sends invoice to the customer. Exceptions: 1. System has no data because it is a beginning of the project or because software developers did not report their work to the system. System shows empty report. 2. Project manager selects customer for whom no work has been done or projects for which no work has been done. System show empty report. Post conditions: Customer is being invoiced. Effort for which customer has been invoiced is recognized by the system. Use case: Sprint closing report. Id: 005 Summary: Sprint is being closed. Project manager analyzes all activities done during the sprint and closes those SBLitems which have been marked as completed. SBLitems marked as closed are not visible anymore in SBLitems list. Actors: Project Manager Preconditions: Sprint has ended and new sprint is starting. System contains information on activities done during last sprint and on SBLitems which have been accomplished during that time. Basic sequence: Step 1: Project manager opens systems and selects appropriate report type. Step 2: System presents all SBLitems that are part of particular sprint.system shows SBLitems that are completed. Step 3: Project manager selects completed SBLitems for closing. Step 4: Selected completed SBLitems are marked as closed and are not shown anymore in SBLitems list. Exceptions: 1. System has no data because it is a beginning of the project or because software developers did not report their work to the system. System shows empty report. 2. No SBLitems have been completed during particular sprint. It is not possible to close any SBLitem. Post conditions: Closed SBLitems are hidden and not shown in SBLitems list. Internal use 14

15 Use case: Insurance report. Id: 006 List of all SBLs with all fields included in SBL excluding dependants (all properties, relations and 3 fields representing tracked values) - desired is that in this report relations appear as links (to bugs, test mandates, rbls or whatsoever SBL is linked to) - for tracked values it includes following fields - (initial) estimated left all (first value) - (current) estimated left all (last value) - (total) accomplished (sum of all values) Summary: Avain Technologies stuff is not happy with Artifact Tracker system and wants to transfer all the data in the system to old Excel sheets. Insurance report delivers all important data in XML format so it can be easily transferred to XSL. Actors: Project Manager Preconditions: Artifact Tracker has been used and there is data in the system. Basic sequence: Step 1: Project manager opens systems and selects appropriate report type. Step 2: Report is generated that contains all fields included in SBLItems excluding dependants (i.e. all properties, relations and three fields representing tracked values). Desired is that in this report relations appear as links (to bugs, test mandates, rbls or whatsoever SBL is linked to). For tracked values report includes following fields: (initial) estimated left all (first value) (current) estimated left all (last value) (total) accomplished (sum of all values) Step 3: Project manager converts XML data into Excel sheet using separate converter created by Avain Technologies staff. Exceptions: System has no data because it is a beginning of the project or because software developers did not report their work to the system. System shows empty report. Post conditions: Customer receives XML report that contains all information necessary to start using Excel sheets again. Internal use 15

16 7. Functional requirements 1. The system MUST have a web browser interface for all of its daily-use functions. No web interface is needed for configuration. 2. The system MUST be capable of tracking estimated and actual effort associated with artifacts. It MUST maintain a log of estimated remaining and actual effort entries, stored with the date each log entry was made. 3. The system MUST implement the following daily-use functions for the artifacts defined in it: Create new instance of artifact Copy existing artifact as new artifact Modify existing instance of artifact Update estimated and actual effort expended, if so configured in artifact description Enforce lifecycle of artifact, as configured in artifact description Filter artifact lists by user-specified criteria (based on the artifact configurations) Include functionality needed for using the system in a cyclic process, including but not necessarily limited to: 1. Closing all resolved cyclist instances as a batch Allow creation of following relationships between different artifact types: 1. Belongs to (is a child of) 2. Is a parent of (owns) 3. Exists only if... exists Be able to generate sufficient reports of the data contained within the system (e.g. by artifact, by owner). See below for details. 4. The system MAY implement the following functionality, time and resources permitting, and MUST NOT preclude implementation of such functionality in the future: Authentication and authorization at a sufficient level to restrict system access to authorized personnel Cost tracking and cost estimation per artifact (based on cost of labor and estimated/actual effort) Internal use 16

17 Connectivity to other systems via standard interfaces (SOAP, Web Services, LDAP, JDBC ) notifications 5. The reports must be configurable like the artifacts themselves. Views include but are not necessarily limited to hours by developer (summarizes all artifacts that contain effort tracking that belong to the developer), hours by artifact (summarizes all estimated and actual hours associated with the artifact, including following parent-child dependency links, e.g. RBL item to associated SBL items), and hours per customer (summarizes all artifacts that contain effort tracking that belong to the customer). 6. If there is time to do it make it possible to create a child from the parent (e.g. click on a "Create SBLItem" button from the "Edit RBLItem" view, where the SBLItem would inherit the association with the RBLItem.) 7. Customers and accountants require a log of hours arranged by developer or project and the date they were recorded. The system must be able to provide such logs. Example: Task Hand-off X-Sign 2a to Serv, Testing Support Testing with test routines implement <aftersignaturecalc>, <extrachecks> Implement <precalc> Total Who actua l Aydi n 4 4 Aydi n Aydi n Aydi n Internal use 17

18 8. Properties (quality requirements, non-functional requirements).1 The system MUST be written for easy understandability and maintainability. Technologies must be used in a disciplined way (e.g. XML Schemas must be written for all critical configuration files)..2 System should be based on Cocoon 2.1 or newer version..3 The system MUST be customizable and expandable. It must be possible to add, remove, and modify types of artifacts and their life-cycles without modifying the source code of the system, by modifying XML configuration files. Owners must be similarly configurable. Internal use 18

19 9. References 1. Rautiainen K., Lassenius C., Vähäniitty J., Pyhäjärvi M. and Vanhanen J.: A Tentative Framework for Managing Software Product Development in Small Companies. Proceedings of the 35th Hawaii International Conference on System Sciences Vanhanen J., Itkonen J., Sulonen P.: Improving the Interface between Business and Product Development Using Agile Practices and the Cycles of Control Framework. Working paper, Helsinki University of Technology, Internal use 19

20 10. Changes history Version Date Author Changes Approved by Michal Pilawski First version of the document Michal Pilawski Changes to the document on the requests from Kristian Rautiainen and Petteri Sulonen: 1. Some minor changes to section 2 more elicit statement of the fact that the core of the system can be used with artifacts that are specific to other than 4CC processes. 2. Section three major changes in section and graphs. 3. Section 4 rewritten. 4. Section 5 user groups more explicitly described in the table. 5. Section 6 old use cases replaced by 5 new ones Michal Pilawski Changes to the document requested by Kristian Rautiainen 1. Minor correction to use cases graph (Graph 3) 2. Basic changes in use cases Michal Pilawski Layout changes Michal Pilawski New small functions added to requirements Michal Pilawski Use Case IV changed, USE Cases V and VI added, some functionalities added. Internal use 20