Integrate Costs and Issues into CodeScene¶
CodeScene provides an optional integration to Project Management tools like Jira. The integration has the following pre-requisites:
Issue numbers are included/referenced in the commit messages or pull requests/branch names.
You use labels and/or issue types to distinguish different kinds of work (e.g. Bugs, Features).
When present, CodeScene’s Project managment s integrations let you measure:
Accumulated costs per hotspot and sub-system.
Trends by work type, such as “Planned” versus “Unplanned” work.
CodeScene’s cost analyses let you reason about the technical and organizational findings from a financial perspective. For example, how much time do you spend on defects in your top hotspots? What amount of work is unplanned? And what happens over time?
CodeScene supports multiple cost models depending on the data you have available such as cycle times, story points, or time spent. CodeScene can deduce costs automatically based on your development history, so you don’t even need to have developers reporting their time to be able to get a detailed view of your development costs. We cover all options and provide our recommended setup in this guide. Let’s start by looking at the overall model.
CodeScene’s Cost Model¶
CodeScene offers a breakdown of the development costs on three separate levels: file-, architecture-, and system-level. The file level corresponds to the hotspots, the architecture level accumulates costs on a component/service/module level, whereas the system level presents the cost trend as aggregated for all application code.
Using CodeScene’s cost model, you get the specific development costs on each hotspot. Use this data to inform re-work decisions and to communicate the costs of technical debt to the business:
For larger hotspots, it might not be realistic – nor financially wise – to refactor a whole module. For that purpose, CodeScene comes with its X-Ray analysis that lets you break down the defect statistics to a detailed function level.
Calculating Development Costs: the four options¶
There are four strategies, and you need to select one of them depending on what data you have in your project management tool:
Estimated development time: calculate a cycle time for the number of hours from the time an issue entered a specific state until the last commit is done on this issue. The cycle time is then adjusted for the number of hours in a typical work day. That is, a cycle time of 3 days has a cost of 3 * 8 hours. In addition, CodeScene distributes the total costs proportional to the change impact when multiple modules/files are modified for the same issue. This cost model lets CodeScene calculate costs as opposed to rely on time reported in the project management tool, which is often incorrect, incomplete, or both.
Issues: the number of issues associated with a given file or architectural component. Use Issues to get a summary and inspect general trends, but without assessing actual time spent.
Points: the cost of an Issue in /Story points/. This method requires that points has been reported on the specified cost-field in your PM tool. Use this option if you keep track of story points and use them to communicate within the organization.
Minutes: the cost expressed in time. This method requires that time has been reported on the specified cost-field in you PM tool. Use this option if you have accurate data on how much time you have spent on each issue.
Export Cost Data to Excel/CSV¶
All cost trends in CodeScene provides a button that lets you export to a CSV file and explore further details in a spreadsheet application.
NOTE: The exported data use the internal cost units. For issues and story points, this unit is always the unit of presentation in the graphs. However, for time-based cost units like Estimated development time or Minutes, the exported cost is in minutes. This typically differs from the values presented in the graphs since CodeScene converts them to more suitable visual presentations (e.g. hours, days).
Configuration¶
Connect CodeScene to Jira¶
Jira is enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “Jira”:
Fill in your Jira credentials here. We recommend using a Jira API token as the password. Note also that a separate token for accessing GitHub is necessary when selecting the option to extract issue numbers from GitHub Pull Requests.
You also have to specify a cost model that determines how CodeScene calculates the costs. The cost model options are described earlier in this document.
Once you press “Save and Continue”, you are presented with the detailed configuration options. See further below in this document for a detailed walkthrough of the configuration options.
Connect CodeScene to Trello¶
Trello is enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “Trello”:
You need an API Key and an API token from Trello. You generate those credentials via the Trello app-key .
You also have to specify a cost model that determines how CodeScene calculates the costs. The cost model options are described earlier in this document.
Once you press “Save and Continue”, you are presented with the detailed configuration options, as specified above.
Connect CodeScene to Azure DevOps¶
Azure DevOps is enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “Azure DevOps”:
You need an access token from Azure Devops. See Authenticate access with personal access tokens . Assign the Code:Read (to read pull requests data) and Work Items:Read scopes.
You also have to specify a cost model that determines how CodeScene calculates the costs. The cost model options are described earlier in this document.
Once you press “Save and Continue”, you are presented with the detailed configuration options, as specified in the next section.
Connect CodeScene to GitHub Issues¶
GitHub Issues are enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “GitHub Issues”.
You need an access token from GitHub with repo permissions. See Creating a token .
Once you press “Save and Continue”, you are presented with the detailed configuration options, as specified in the next section. Note that the GitHub Issues integration supports only the Issues cost model.
Connect CodeScene to GitLab Issues¶
GitLab Issues are enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “GitLab Issues”.
You need an access token from GitLab with read_api permissions. See Create a personal access token .
Once you press “Save and Continue”, you are presented with the detailed configuration options, as specified in the next section.
Connect CodeScene to YouTrack¶
YouTrack is enabled and configured per project. Navigate to the “PM Integration” tab in your project’s configuration and select “YouTrack”.
You need an permanent token from YouTrack. See Creating a permanent token .
Once you press “Save and Continue”, you are presented with the detailed configuration options, as specified in the next section.
Specify the Detailed Configuration Options¶
External Projects: Select one or more projects in your project management tool that CodeScene will use as data sources.
Work In Progress Transition Name: Specify the names of the issue statuses that indicate that the development work has started. Often, this is the “In Progress” or “In Development” state.
Supported Work Types When using issue labels to identify work types, you need to select the labels that are to be included in the analysis.
Defect Work Types: Specify the Work Types that will be regarded as defects. This configuration is used to calculate defect densities and work type trends.
The Rename Work Types field allows the work types to be mapped to different analytical categories that you can define yourself. How you do this depends on the type of analysis you wish to perform.
Cost Field: Is used only for the cost models Points and Minutes. Select the issue field that has your cost estimates. If you don’t use Points and Minutes as cost model, then it is not necessary to configure Cost Field and you can leave it as is. Note that this option is not available for all integrations.
Tip: Rename Work Types to distinguish Planned and Unplanned work¶
When looking at cost trends, the most interesting distinction is typically between Planned- versus Unplanned Work.
By specifying Rename Work Types option, the Jira labels are translated to the specified label before being sent to CodeScene. For example, if your Jira project contains Feature and Documentation labels, like in the illustration above, these can be categorized together as Planned Work, while Bug and Defect are treated as Unplanned Work; the Refactoring label – which doesn’t have a translation – will be sent as is. Mapping labels this way can allow you to see more meaningful trends. You are free to map labels however you like depending on your analytical needs.
Advanced Information¶
Measures to reduce bias in the trends¶
Let’s face it: Project Management data can be noisy. CodeScene reduces as much of this noise as possible via its data cleaning:
Cycle time in development: improve the precision by identifying issues that have a transition to “In progress” _after_ the last commit related to that issue. CodeScene then fall back on using the date of the first commit as starting point to recover part of the cycle time.
Issues that lack a cycle time: even with the previously mentioned fallback mechanisms, some issues might be implemented with just a single commit. Hence, there’s no way of measuring the actual time in development. To avoid losing valuable data, CodeScene applies a default cycle time of one working day (8 hours).
CodeScene’s Cost Distribution¶
CodeScene’s cost model contains a number of features that reduce bias in the available cost data. For example, let’s say that you have an issue with the known cost of 100 hours. In that issue, the developer spent 95% of the time working on one complex hotspot, and then just made a simple tweak to a config file. How should those 100 hours be split between the impacted files? Assigning “100 hours” as cost to each file is clearly the wrong thing to do as it exaggerates the development cost of that simple config file.
For this purpose, CodeScene distributes the calculated costs for a specific issue on two orthogonal levels: 1) across impacted modules, and 2) across the relevant types of work.
Distribution across modules: CodeScene distributes the derived costs proportional to the change impact when multiple modules are modified as part of the same issue. That is, the modules with most work in a specific issue get proportionally higher costs than modules that had less work. CodeScene automatically deduces this distribution.
Distribution across issue types: Since an issue can have multiple issue types and labels, CodeScene distributes the costs equally across all referenced types of work for the specific issue. This is relevant to the cost trends in CodeScene. For example, let’s say we have a cost of 100 hours for a specific issue and entity. The issue has two labels in Trello: Feature and UI. CodeScene will distribute the costs so that each of those types of work, Feature and UI, get 50 hours as their costs.
NOTE: The cost unit issues is a special case since issues are never split; it doesn’t make sense to say that the cost of a specific module is “3.25 issues”. Instead CodeScene selects the first known issue type for that issue and assigns it the cost.