Chapter 13. Reporting Changes

Reports for large systems provide an overwhelming amount of information. Most of the times a report containing the changes compared to a baseline is enough - like a newspaper versus a whole encyclopedia. This delta feature can be invoked within Sonargraph Architect via "File" → "Calculate Diff" . On first invocation this interaction will generate a XML report to a data directory within the Sonargraph application home directory. On second invocation the current system information will written to another XML report and compared against the baseline. The old baseline report is replaced by the new report, so that this menu provides an easy way to inspect the differences between two points in time.

If you generate XML reports at regular intervals, e.g. automatically via SonargraphBuild, you can also compare the current system against a baseline report of your choice via "File" → "Calculate Diff Against Baseline XML Report..."

If reports are generated at the beginning and end of a feature implementation, the delta report provides a quick overview about changes related to Sonargraph issues and how the overall state of the system has been improved.

The delta report is currently plain text. An example report is shown below (lines have been truncated) that shows differences in issues:

Delta of System Reports:
   Report1 (baseline): D:\00_repos\sonargraph-integration-access\src\test\diff\AlarmClockMain_01.xml
   Report2           : D:\00_repos\sonargraph-integration-access\src\test\diff\AlarmClockMain_02.xml

System Info: 
   Name: AlarmClockMain
   ID: 6db0a52dfa66892be8a4bc2bb7cf1720
   Path: D:\00_repos\sonar-sonargraph-integration\src\test\AlarmClockMain\AlarmClockMain.sonargraph

Delta of Systems
   System 1 (Baseline): AlarmClockMain from Nov 30, 2016 5:01:13 PM
   System 2           : AlarmClockMain from Dec 30, 2016 5:01:13 PM

- Issue delta:    
    Removed (13):
        EmptyArchitectureElement, generated by Core: Artifact 'Foundation', line 1, resolved 'false'
        Potentially dead method, generated by ./Java/BadSmells/FindDeadCode.scr: Method has ...
        Potentially dead type, generated by ./Java/BadSmells/FindDeadCode.scr: Type has no ...
        Duplicate Code Block with 2 occurrences, block size '52', resolved 'false'
         Occurrence in ./com/h2m/alarm/model/AlarmClock.java, start '52', block size '52', ...
         Occurrence in ./com/h2m/alarm/presentation/Main.java, start '34', block size '52', ...
        JavaFileClassFileMissing, generated by JavaLanguageProvider: Missing class file for ...
    Improved (1):
        Previous: ThresholdViolation, generated by ./Java/BadSmells/FindDeadCode.scr: Potentially ...    
    Worsened (1):
        Previous: ThresholdViolation, generated by Core: Total Lines = 106 (allowed range: 0 to ...    
    Added (6):
        Supertype uses subtype, generated by ./Core/SuperTypeUsesSubType.scr: Reference to ...
        ArchitectureViolation, generated by ./Layers.arc: [Local Variable] 'Model' cannot access ...

If present, the report also shows differences in the core system configuration (i.e. licensed features, active analyzers, metric provider, metric ids, etc.), workspace configuration and resolutions.

The delta computation of two XML reports is implemented in our Open Source project "Sonargraph Integration Access" that is hosted on GitHub at https://github.com/sonargraph/sonargraph-integration-access . Thus, you can embed the report delta computation easily within your own custom build pipeline if the integration with SonargraphBuild does not satisfy your requirements. The functionality is available in Integration Access 3.0.0 and newer. It can be called with the following command-line and two mandatory arguments: The first being the baseline report and the second the XML report that is compared against the baseline. If no output file is specified as the third parameter, the info is printed to the console.

        java -cp ../../target/sonargraph-integration-access-3.0.0.jar
        com.hello2morrow.sonargraph.integration.access.ReportDiff
        <path-to-baseline-report-xml> <path-to-report-xml> <optional: output-file-path>

Current Limitations

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

Cycle groups issues and duplicate code block issues consist of several parts that contribute to their unique IDs. If one of these parts changes (for example a source file has been renamed) then the issue's ID is changed.
If a script or an architecture file is renamed, the origin of the issues generated by those resources is changed.
For some issues the originating line within a source file is stored and used for comparison. Changing unrelated lines in the source file before the issue's origin therefore will cause the issue to be treated as changed.

NOTE

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

Ideas for feature improvements are to include the baseline report as filter in Sonargraph Architect/Explorer to let the user focus on changed issues.

Prev		Next
	Home