Upsource Analytics: Project Structure Reports

Vladimir Kovalenko

In the previous post we have talked about the Analytics reports representing contribution and code review activity. Today we’d like to cover the two remaining reports, Project Treemap and File History Chart. They both focus more on exploring the project structure rather than its history.

Project Treemap

As a developer, once you start getting familiar with a repository that you have never seen before, it usually takes a while to build the understanding of the codebase structure: where most of code is located, what are the key elements of the codebase, which parts of it are changed more frequently, and which ones are hardly ever edited.

Introduced in Upsource 3.0, the Project Treemap report gives a bird’s eye view of the project structure.

The color of each tile shows how often the file or the contents of the directory are changed
compared to their siblings. A glance at the treemap view of the root directory gives an overall idea of which parts of the project receive more development effort.

The size of the tiles can represent the total size of content, number of files, or number of changes ever made to a folder. You can browse deeper into the tree and back to see more details.

The controls on the right can be used to select the extensions of files to include in the view.
It might be helpful if you do not want bulky files like .jar artifacts or test data to impair the picture.

Project Treemap not only provides an overview, but also reveals files and directories with unusual maintenance patterns. This knowledge is of great help for the team when it comes to identifying the candidates for refactoring or planning where to put more QA effort.

In the picture above, the treemap view of Apache Maven core sources directory, there is a clear deep spot: one of the files is edited much more often than average. The situation when one of the files receives by times more development effort than its siblings is always worth developers’ attention: it may be a sign of a design problem. Such files very often turn out to be the key points of the codebase – or its deeper corners demanding refactoring.

This example is not an exception: the deep blue file is DefaultMaven.java, the default implementation of the main interface of the whole tool. The Project Treemap view is essential to quickly locate such hotspots.

Project Treemap lets you learn a lot about the overall project structure in a short time, as well as guide you through the points of interest in the codebase.

It is also fun to browse a codebase you are familiar with – you might be surprised to see some numbers!

File History Chart

File History Chart is another report that can help you locate the files with unusual maintenance patterns.

This animated chart shows how the project files were edited over their history.

Each point represents a file in the repository.
The higher the point is, the more edits the corresponding file experienced.
The closer the point is to the right edge, the more recently the file was edited.

Typically, most points are located not too far from each other. Still it is likely that there will be a few outliers – these files may be demanding more attention or even refactoring, like the color spots in Treemap.

One thing File History Chart is particularly good for is finding the abandoned files: the files that experienced enough edits to be among the most edited, but have not been edited for a long time. These files will be represented by the points lying closer to the middle of the chart than most.

The version control system knows everything about the project and its history. Some of the data, like source code or list of committers, is always available explicitly. Upsource Analytics is capable of unraveling the less obvious sides of history of your projects to help support your development and management decisions. Use it wisely!