Chapter 14. Examining Changes

Sonargraph provides an overwhelming amount of information for large systems. Most of the times comparing the information against a baseline and focussing on the changes is enough - like a newspaper versus a whole encyclopedia. This feature is available in Sonargraph via the "System Diff" view that can be opened via "Window""Show View""System Diff" . The baseline is represented by an XML report and can be applied by clicking the links at the top of the view opens the dialogs:

  1. "New Baseline": Allows creating and directly applying a new baseline, e.g. at the beginning of a feature implementation or before changing the software system. Adding some context info makes it easier to identify the report later on.

  2. "Open Baseline": Allows selecting an existing XML report from disk, e.g. to compare the current system against a report generated by Sonargraph-Build at the end of the last sprint. Previously selected baselines are displayed in the table with the most recently used at the top.

  3. "Download Baseline": Allows downloading an existing XML report from your Sonargraph-Enterprise server.

  4. "Export Diff Report": Generates a HTML report of the current diff information.

  5. "Detach Baseline": Disables the System Diff analyzer. This is useful to speed up processing when you modify the configuration for a large system.

    TIP

    The same can be achieved by changing the analyzer execution level to anything below "Full" via the menu "System""Analyzer Execution Level".

Two types of baselines can be created: "System" and "Local" baselines. A system baseline is meant to be useful for all users of the Sonargraph system and is used by Sonargraph-Build. Thus, it is stored in the Sonargraph system's directory "Baselines". System baselines are usually created at the beginning or end of a release. A local baseline is only useful for the current user and usually has a shorter life-span. Examples are baselines created before a feature is implemented.

TIP

If a baseline is generated at the beginning of a feature implementation, the System Diff view provides a quick overview about changes related to Sonargraph issues and how the overall state of the system has developed.

NOTE

This functionality is only available in the commercial version of Sonargraph.

Differences are detected related to the system configuration (path, name, features, analyzers, scripts, plugins), system-level metrics, workspace (filter, modules, root directories), issues, resolutions (ignores, tasks, refactorings), cycle groups, duplicate code blocks and Architecture Models, i.e. checked architectures. More information about a detected change is provided in the "Details" column. The comparison for architectures is done on the 'model' level, i.e. changes in comments, formatting changes and changes that do not alter the semantic of the model are not reported. The following screenshot shows changes in the issues view with a focus on cycle group issues:

System Diff View (Issues)
Figure 14.1. System Diff View (Issues)


NOTE

Since the cycle group names are not stable, the matching is done based on the contained elements. If up to 40% of the cyclic elements have changed, the cycle groups are matched, otherwise they are treated as different groups and are reported as removed from the baseline and added in the current system.

A similar approach is taken for duplicate code blocks, where the individual occurrences are matched against each other, tolerating extension and shortening of blocks.

The following types of changes in cycle groups are detected:

  1. Added: Cycle group was not present in baseline.

  2. Removed: Cycle group existed in baseline but is no longer present. If two or more baseline cycle groups are integrated into a single cycle group or a baseline cycle group is split into several smaller cycle groups, this is indicated in the "details" column.

  3. Improved: Cycle group consists now of fewer elements and/or has fewer parser dependencies to remove.

    If a cycle group is the result of splitting a baseline cycle group, this is indicated in the "details" column. Cyclic elements of this group are reported as added.

  4. Worsened: Cycle group consists now of more elements and/or has more parser dependencies to remove.

    If a cycle group is the result of integrating two or more baseline cycle groups, this is indicated in the "details" column.

  5. Modified: If up to 40% of the cyclic elements have changed but the number of cyclic elements in the cycle group is the same it is identified as the same group and marked as modified.

If a worsened cycle group is opened in the Cycle view, the added elements are highlighted. See “Highlighting Added Cyclic Elements” for details.

The tab "Cycle Groups" provides additional details about the added/removed cyclic elements. Filter options on the top-right corner of the tab allow to hide unmodified cyclic elements or issues with resolution.

System Diff View (Cycle Groups)
Figure 14.2. System Diff View (Cycle Groups)


Current Limitations

The following changes only indirectly affect the Sonargraph issues, but will be treated as changes by the diff detector. The issues in the baseline report will be reported as removed and the issues from the current system as added, despite the fact that the issues are logically the same:

  1. If an element (e.g. type, method) or one of its parents (e.g. namespace, module, root) is renamed, its fully qualified name changes and thus its issues are reported as changed.

  2. If a script or an architecture file is renamed, the origin of the issues generated by those resources is changed.

  3. If artifacts in architectures are renamed, the resulting issues cannot be matched.

NOTE

As with every modification: Frequent and small changes are easier to review than big-bang refactorings.

This feature has been introduced with the Sonargraph release 9.13 and we will continue improving the precision of the results and integrating it into other views in upcoming releases. Feedback is always welcome and can be sent to .

Export Diff Report to HTML

The System Diff view allows exporting the current info to HTML as the following screenshot illustrates. Sections that contain changes are marked with an exclamation mark "(!)" in the navigation area on the top left.

HTML Diff Report
Figure 14.3. HTML Diff Report