Reuse of analysis methods and tools for data from di erent issue management systems is challenging because there are di erences in how the data is accessed and represented. While various approaches for collecting and analysing software engineering data have been developed, they do not generally pay so much attention into how to actually get the data from various sources. This paper presents a combined model for issue management data that is based on an investigation of four issue management systems. It also presents a proof of concept tool that can collect issue management data from di erent services into our analysis and visualization framework using an API description language that denes how to get the issue management data and how to convert it into our model. The aim of this approach is to allow the addition of new data sources by simply providing their API descriptions.
Issue management is an integral part of software development and management.
Various tools have been developed for that purpose e.g. Jira and the issue
tracking feature of GitHub. The information collected into the issue management
system can be used to analyze the software project and it can give valuable
insights, that can help in managing the project, e.g. how to automatically identify
valid bug reports [
Many issue management systems o er an API that can be used to acquire data. A tool, that could fetch issue management data from multiple sources and o er the same interface and analysis features regardless what the data source is, would be useful for both its users and developers. There are some di erences in how di erent issue management systems handle and represent issues and related concepts. Thus if the same analysis tools and notations are to be used to analyze issues from multiple sources, a common model for issue management has to be de ned. Also a generic method for collecting issue data from di erent sources and converting it into this model has to be developed. This paper presents a combined data model based on four di erent issue management systems. It also presents a tool that uses API descriptions in collecting and converting issue management data from di erent services.
This paper is organized as follows. Section 2 discusses the motivation and background of this research in more detail. Section 3 presents our investigation into di erent issue management systems. Section 4 describes the combined issue model that is based on the investigation. Section 5 describes the implementation of a issue collection tool that uses API descriptions in collecting issue management data according to the model. Section 6 presents discussion about our approach. Section 7 presents related work and section 8 presents conclusions. 2
An issue management system serves many purposes in an organization. It is a
knowledge repository, a communication and collaboration hub and a
communication channel for requests for new features, bug reports or any task that
development team should perform [
This research is related to previous research done in our department
considering software engineering data analysis and visualization. In [
In our previous work we have also developed a method for building Internet
service compositions [
To nd a model for issue management data, we surveyed four web based systems that o er issue management. The systems were Jira1, GitHub2, GitLab3 and Bitbucket4. Jira is a dedicated issue management system. GitHub, GitLab and Bitbucket o er code project hosting that include in addition to a issue tracker a code repository based on a version control system. We investigated what information a issue holds, what other concepts are related to issues and how the systems record changes and other activity related to the issues. 3.1
First we de ned what information an issue contains, i.e., the properties of the issue. We listed the properties from each system and combined those that meant the same thing. Properties can be simple attributes or relations to separate entities, who have their own attributes. We found 26 di erent properties and 9 of these properties are common to all the systems. All issues have some kind of unique identi er, a title or summary and a longer explanation about the issue. The issue systems also record when an issue was created and when it was last updated. Issues also have a status or state that indicates the current phase in the work ow. Possible states in the work ow varies by system from just opened and closed o ered by GitHub to the user customizable work ows of Jira.
All of the systems have authenticated users and they can be related to an issue as the creator. All systems support also assigning the issue to a user who then is responsible for progressing the issue's resolution. Issues can also be discussed in all systems with a commenting feature.
Two properties issue labeling and associating issues to milestones are shared with three of the systems. Seven properties are shared between two systems. In six cases those systems are Jira and Bitbucket. They let issues be categorized with types, o er possibility to associate issues with software versions and speci c components. They also allow issues to be prioritized.
Jira is the most advanced of the systems. It o ers eight properties that the other systems do not o er. It allows the type of the resolution to be recorded for example xed or cannot reproduce. It also o ers features for estimating and recording the amount of work for the issue. Issues in Jira can also be linked to related issues. In addition Jira is customizable o ering a possibility to add custom elds. 3.2
All of the systems record changes to the issues such as changes in the issue state and properties. What changes are recorded and how they are accessed varies. In
all of the systems the user who made the change and the time the change was made is recorded.
GitHub records issue changes as issue events. They can be accessed for the whole project or for a speci c issue. These events have a type that indicates what kind of change the event represents for example closed, opened, assigned or labeled. The event contains also information about what the change was e.g. what label was added to the issue. GitLab has project speci c events that include events about issues but have other events also. There are events only for issue opening and closing. Some other changes such as labeling or assigning are just saved as comments of the issue
Bitbucket has also project events. However the feature is limited since only 30 most recent are available. Their content is also quite limited. There are events for issue creation, commenting and updating but the update event does not have speci c information about what was updated and the creation event does not tell what issue was created. In Jira each issue has a changelog. It records each change of the issue. A change record contains the property whose value was changed, its old value and the new value. 4
This section presents the issue management data model that we developed based
on our investigation of the issue management systems. It also shortly presents the
uni ed software engineering data model used by our analysis and visualization
framework, presented in [
Our investigation shows that issues in the di erent systems have quite much in common. This enables the de nition of a combined model for issues. It has eight di erent entities: issue, user, comment, milestone, version, component, label and change event.
An issue in our model has all of the properties presented in section 3.1. Most of them (18 out of 26) were shared at least with two of the systems and the rest are also useful. Table 1 lists the properties of an issue with their types and descriptions.
Label, milestone, version and component are similar simple entities. They have a name and a description and can be associated with issues. Milestone has also a due date, a creation time and a closing time. User represents a user of the issue management system. It can be associated with a issue as the issue creator and as an assignee. Comments consist of the comment message and the commenting time. They are associated with an issue and the user who posted the comment.
Each issue has a changelog. It consists of change events that record when the change was made, and optionally what property was changed and how i.e. what is the new value for the property. Change event is also associated with the user who made the change.
Property id number title description state author user created datetime updated datetime assignee user comments count integer comments change log labels milestone priority type resolved a ects version
x version component watchers resolution environment votes due estimate remaining logged
Type Description string An unique identi er for the issue in the
management system string An unique identi er for the issue in a project that is not unique in the whole system string Describes the issue shortly string A longer explanation of the issue. string The current state of the issue in the issue work ow User who created the issue When was the issue created When was the issue last updated The person who is responsible for the issue.
How many comments there are about the issue list of comments Comments about the issue list of change events Changes made to the issue list of labels Tags that are used to categorize issues. list of milestones Used to categorize issues to be implemented
in a speci c version or sprint string How important is the issue. string The type of the issue e.g. bug, feature datetime When was the issue resolved or closed. version The version the issue a ects version The version in which the issue should be
resolved. component The software component associated with
the issue integer How many users are interested about the issue e.g. they get noti ed about issue changes string How was the issue resolved e.g. xed, won't
x string In what kind of environment the issue oc
curs integer How many votes the issue has datetime When the issue should be resolved integer Original stimate of the time required to re
solve the issue (minutes) integer Current time estimate (minutes) integer How much work has been done for the issue (minutes) 4.2
The uni ed software engineering data model, mentioned in Section 2 and
described in [
The issue management model presented in the previous section works as a domain speci c model for the uni ed model. It can be mapped to the uni ed model and so issue management data can be saved according to the uni ed model. Of the entities issue, milestone, label, component and version are artifacts. Change events and comments are events. Users can be modeled as artifacts or they can be just attributes for events. Additionally events can be generated from some of the entities' time based attributes. For example issues and milestones have an attribute that tells when they were created. From this attribute creation or opening events can be generated. 5
This section presents the implementation of an issue collector tool that uses the issue model and the uni ed software engineering data analysis framework. First an overview of the tool is presented. Then its API description system is presented. Finally a usage example illustrates how the tool works. 5.1
Our web based data analysis and visualization framework [
To test the feasibility of the issue management data model and data collection approach presented in this paper a tool was developed that can fetch issue management data from di erent web based issue management systems according to the issue management model. The data collection involves making HTTP requests to various API endpoints like issues and milestones. The responses to these requests will contain lists of items in the JSON format that should be converted into various entities of the issue management model. After getting the data the tool then converts the issue management data into the format of the uni ed data model and sends it to the database.
The architecture of the tool is shown in Fig. 1. The tool consists of four components. API descriptions de ne how to get issue management data from di erent sources. The user interface handles user input required for the data collection. The API description de nes what input data is required. The Collector uses the user input to get data from a service described by an API description. The Uni er converts the data in to the uni ed model and sends it to the database.
The tool is implemented with Node.js. Currently the user interface is command line based. The current version of the tool does not yet cover the whole issue management model. It can process issues, comments, milestones and change events. 5.2
An API description is a JavaScript object whose properties describe the API. The API description consists of general properties and resource descriptions. General properties describe general information about the API i.e. information that is common to all API calls. Resource descriptions describe information speci c to API calls to one particular resource such as issues.
Table 2 lists the general properties. General properties for an API description include the common part of the API URL, possibly some HTTP headers and query parameters. Headers and query parameters are de ned as simple objects containing key-value pairs where the key is the header or query parameter and the value its value. If the value is not static, the value unde ned is used. This indicates that the value has to come from the user.
For de ning what information is required from the user in the user interface the API description has an userParams property. This information is usually project speci c information such as identi cation of project to be targeted. The value of userParams is a list of objects that contain the name of the parameter
Property BaseUrl authentication list of objects pagination headers query userParams resources and a description of the parameter that is shown to the user. The parameter name indicates where the value will be used. For example it can be used as a value for a header or query parameter that has the same name.
Issue management services can support multiple ways for their API users to authenticate. The authentication API description property lists the authentication methods that the service supports. A value in the list can be a string containing the name of an authentication method that the tool understands. Currently recognized methods are no authentication and HTTP basic. A value can also be an object that de nes a custom authentication method which can contain additional headers, query parameters and user parameters.
Most API calls do not return everything at once. Instead they return up to a certain number of items and the client has to request more. The pagination property de nes how this pagination in API calls is handled. Currently only pagination using a RFC 5988 link header, that has the pagination information, is supported.
The API description can contain multiple properties that have a resource description object as the value. The name of the property indicates what kind of entities the description describes. Currently supported values are issues, comments, milestones and changeEvents.
A resource description is an object whose properties describe a particular API resource, i.e., a concrete API end point that we want to make a HTTP call to. A resource could be for example the list of issues in a project or a list of one issue's comments. Table 3 lists the properties that a resource description can have.
The path property holds the rest of the HTTP request URL. The value is a RFC 6570 URI template whose variables have to be expanded before making the request. Values for these variables are found from the similarly named
Property path query headers
lter item createOpeningEvents bool createUpdatingEvents bool createClosingEvents children parentParams user parameters. The query and headers properties are similar to the corresponding general properties but provide resource speci c information. The createOpeningEvents, createUpdatingEvents and createClosingEvents properties indicate if additional change events should be created from the new entity's created, updated or closed properties.
The lter property can hold a function that is used to choose which items received from the issue management system are processed. The function is given a single item from the response like an issue and its boolean return value determines if that item should be processed.
The children property describes the current resource's child resources such as the comments of an issue. Its value is an object whose properties have resource descriptions as values similar to the general API description. The parentParams property is applicable only in child resource descriptions. Like user parameters its values can be used in the URI template, headers and query parameters but the source for the values is the child's parent entity.
The item property gives information on how to convert one item from the response in to an entity of the issue management model. The properties of an item description object correspond to the properties of the entity to be extracted. The value tells how to extract the value for the new entity's property. For describing how to extract the value we use JSONPath5. JSONPath expressions are used to select a speci c part of a JSON document or JavaScript object. The value of an item description property can be a string or an object. The path property of that object holds the JSONPath expression. The source property tells where the
Listing 1.1. A part of the GitHub API description. Most item descriptions are not shown and only part of the comment's item description is shown. var api = f ' https : / / api . github . com / ' , bhauaeastedhUeernrsl'tU::icsfaert iAoAcncg:eepntt[ :' :' n' oa'opahpuylitlchl aie/tniitosisncua/etvinodcn.og'l li,ethc'utbobar.svi'c3 +g'j,s]o,n ' , upsaegrdiPneaasrtcairmoinps t:: i o['nl if:n kn'aThmheeea:dues'roewr',nnear m'e, o f the r e p o s i t o r y owner ' g , f name : ' repo ' , d e s c r i p t i o n : ' the r e p o s i t o r y name ' g ] , i s s u e s : f '/ repos /fownerg/f repo g/ i s s u e s ' , path : qf uiletrreyert:u: rfnf us ntitacettmeio.:np'u(al lllitr'eemqgu, )e s ft !== undefined ; g , item : f . . . g , createOpeningEvents : true , createUpdatingEvents : true , c h i l d r epnat:h f: c'o/mrempeonst/sf: ofwnerg/f repo g/ i s s u e s /fnumberg/comments ' , parentParams : f number : ' $ . number ' g , iitsesmu e: : ff idpa:th' $: . i'd$ '. i,d ' , source : ' parent ' g , user : ' $ . user . login ' , message : ' $ . body ' , . . . g g g , . . . g; value is to be extracted from. Possible values are item, which means the item received from the service, and parent, which means the parent entity of the new entity. The mapping property can be used to replace the extracted value with another value. If source is the item and there is no mapping information, the object can be replaced with a string containing the path information. 5.3
As an example of the tool's usage we tested the method to collect issue management data from four public open source projects : grip6, glutin7, gfx8 and webgl-noise9. The webgl-noise project is the smallest of the four projects containing 14 issues where as gfx is the largest containing 304 issues. Glutin project has 187 issues and Grip 107 issues. The projects use GitHub as a code repository and issue management system. Thus we require an API description of GitHub's API which is shown in listing 1.1.
When the issue collector is invoked, it rst checks what API descriptions are present and asks the user which of these she wants to use. The issue collector loads the API description the user chose and rst checks what authentication methods are available and lets the user choose the one she prefers. As can be seen on the line 3 of the Listing 1.1 GitHub issue collector can be used without authentication or with HTTP basic authentication.10 If the user chooses basic authentication, the tool next asks the user for her username and password
required by HTTP basic authentication. Next issue collector checks what additional API speci c information is needed from the user. From the lines 7-10 of the Listing 1.1 we see that two user parameters named owner and repo are required. The issue collector queries inputs for these showing their descriptions to the user. Lastly the tool queries the user for some metadata required by the uni ed data model.
Next the collector can begin the actual data collection. It goes through every resource description, makes HTTP requests they de ne and converts the data received into the appropriate entities. For constructing the HTTP requests the collector gets the beginning of the URL from line 2. Lines 4 and 5 de ne that all HTTP requests have to contain two speci c headers. If HTTP basic authentication was chosen the authentication information provided by the user is also added to the requests. Then, for example, from the resource description for issues the collector gets the rest of the URL from line 12. This URI template has two variables owner and repo. The collector gets values for these from the similarly named user parameters. The resource description also de nes on line 13 that the URL has to include a query parameter named state with the value all. After making the request, the collector processes each item in the response. Since on lines 14-15 issues resource has a lter function, that is executed rst and the item is processed only if it returns false. In this case the function is used to lter out pull requests which GitHub includes with the issues.
The API description de nes on line 19 that issues have comments as children. This means that for each issue entity created its comments should be fetched as well. The path on line 20 is expanded with the owner and repo and also the number property of the parent issue. This is de ned on line 21 with the parentParams property. The actual comment entity is constructed according to the information on lines 22-25. It de nes for example that the message property of a comment can be found from the response item's property named body. It also de nes that the id of the issue the comment is related to can be found from its parent entity's id property.
After each item in a response has been processed, the collector checks if the response contains a link header that has the URL for the next page of items, and if it does, it makes a request to it. This behaviour is speci ed on the line 6 of the Listing 1.1. After all entities are collected, the collector checks if additional change events have to be created. For example line 17 de nes that from each issue entity a change event has to be created. This event's change type will be opened and the time the creation time of the issue.
After the collector is nished, the uni er converts the issue management data into uni ed model's artifacts and events which are then send to the database. After this the user can use the visualization framework's analysis and visualization features. Figure 2 has an example visualization from the grip project's data that shows each artifact's events and life spans on a timeline. From the visualization we can see for example how long di erent issues have been open and if the issue has been reopened. Also comment, label, reference and delabel times are visible for each issue. This kind of view enables comparing issue lifespans to each other as well as nding similarities and patterns from issue events. Our issue management data model is based on a survey of four issue management systems. Although there are many more issue management systems we believe that our model covers the most important aspects of issue management. However in our future work we should verify our model by using it with systems that we did not survey and if the need arises to expand our model. Our model is quite simple and not as expressive as for example an ontology based approach. However, our aim was a light weight model for data storage and testing the API description approach, and for that purpose we believe our model is suitable.
The implementation of our issue collector tool shows the basic feasibility of the model. We used the model successfully with GitLab and GitHub for which we currently have API descriptions. The implementation and those API descriptions also shows the feasibility of our data collection approach. This approach has its strengths and weaknesses. The descriptions are declarative so a description author does not need to worry how the data is collected. When the APIs behave similarly such as GitHub and GitLab do when fetching issues and their comments, the approach works well. However, when there are di erences in how things are done like with change events, the tool's implementation and API description have to take them in to account, which will cause complexity in the implementation code and in the API description syntax. API rate limiting of the services can cause problems when fetching data from bigger projects and we must nd ways to deal with them. Currently the tool is a proof of concept implementation and probably new issue sources such as Jira and Bitbucket could not be added just by adding their API descriptions since there are many things the implementation does not support yet. For example pagination is supported only with a link header which all services do not support so a custom pagination implementation would be required. More advanced data extraction features for more complex data structures are also required.
In our previous work on Internet service compositions [
On a high level this work can be seen to be related to research into extract,
transform and load (ETL) processes used in data warehousing to integrate data from
di erent sources for business reports. ETL research deals with similar problems
as our research such as how to combine data from di erent schemas into a single
schema and what is the work ow of the ETL process [
Some approaches use semantic web technologies and de ne an ontology for
software engineering data. Kiefer et al. [
Evolizer [
Analysis of issue management data can give useful insights in to a software engineering project. In our previous work we had developed an uni ed software engineering data model and a framework for storing and accessing it. Collecting issue management data from various sources and converting it in to the uni ed format for analysis presents challenges. We tackled these challenges by rst investigating four di erent web based issue management systems. Based on that we developed a combined issue management data model. It consists of eight entities such as issue, milestone and comment. These entities, their properties and relations cover the essential parts of issue management and allows data from various sources to be stored and analyzed.
We also developed a proof of concept issue data collection tool which collects issue data according to our issue management model and then converts the data into the uni ed data model's format. The tool uses declarative API descriptions which de ne how data is fetched and converted. The current version of our tool is limited but it proves the feasibility of our approach. The end goal of our approach is to allow new data sources to be added quickly just by providing an API description that can then be used to fetch data from di erent projects in that source. We believe that this approach can be expanded to cover di erent types of software engineering data such as version control data. In our future work we will explore the potential of this approach with other issue management systems and other kind of data. This approach might also have uses in other contexts.
The research has been supported by Tekes-funded Digile project Need for Speed11 and by Foundation of Nokia Corporation12. 11 http://www.n4s. /en/ 12 http://www.nokiafoundation.com/