Reporting Code Diff

Normal

0

21

false

false

false

FR

X-NONE

X-NONE

Share/Bookmark

Several
NDepend users asked
our support how to automate showing diff in report. The goal for example, is to list all
assemblies/namespaces/types/methods/fields that have been added/changed/removed
since the last release. Here are the 3 steps:

 

Step1: Define the base line

First,
define the base line, meaning, the previous versions of the code base against which the comparison
will be done. This can be done in VisualNDepend > Project Properties > Analysis > Build Comparison.

 

 

Step2: Define the diff rules and activate them

Second,
define your own diff CQL
rules
that match your particular needs. By default, an NDepend project comes with a set of default CQL diff
queries. They can be found into the Diff \ Changes \ Evolution >
Change Summary CQL default group. Selecting a diff query makes appear the matched diff result in the CQL Query Result panel of VisualNDepend.

 

However the result of a CQL query cannot be shown in report. Only result of CQL rules can be shown in the
report, under the conditions:

  • The CQL rule is violated.
  • The CQL rule is
    activated.
  • The option Display list of items selected in report
    must be selected.

Thus, a CQL query needs
to be transformed into a rule. This is as simple as adding the prefix WARN IF Count > 0 IN to the query. Notice
that we activated the rule + we selected the option Display list of items selected in report:

 

You need also to make
sure that all parent CQL group of your CQL diff rules are also activated.

 

Step3: Show diff rules in report

Et voila, the
list of methods added is listed in the report.

 

 

Do More

Actually, before being listed in the report, result of violated CQL rules
are stored into an XML file named CQLResult.xml.
This file is stored in the output folder of the NDepend project. If you wish
to do more customized report you can easily parse the XML results. It is part
of the future plans to propose more facilities to harness automatically results.

 

 

Finally, while reporting
is great, a report will never be as informative as the real-time browsing capabilities
offered by VisualNDepend. Since NDepend version 2.12 a Search Panel is proposed to readily explore the diff between 2
snapshots of your application.

 

Share/Bookmark

This entry was posted in Build Comparison, Change summary, Code Diff, Report. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://codebetter.com/members/Patrick-Smacchia/default.aspx Patrick Smacchia

    James, just use some CQL rules specific to breaking changes, as explained here
    http://codebetter.com/blogs/patricksmacchia/archive/2008/01/20/avoid-api-breaking-changes.aspx

    and tune your build process to trigger an NDepend analysis everyday (with comparison as explained in the post)

  • James Davison

    Great tutorial Patrick, it really helped me get a feel for how to create something like this. We’re looking to replace our current build comparing tool with this.

    However I, for the life of me, can’t figure out how to automate the process so that each day it will automatically generate a report with just the breaking changes in the API. Any tips?

  • http://codebetter.com/members/Patrick-Smacchia/default.aspx Patrick Smacchia

    Travis, measuring coverage on Diff is actually one of my prefered features.

    I wrote a post dedicated to ‘diff in coverage’:

    codebetter.com/…/are-you-sure-added-and-refactored-code-is-covered-by-tests.aspx

    …and since then, the NDepend v2.12 version came with a new Search Panel that has a specific ‘Search for Coverage of Changes’ option.

    So you just need to adapt your diff rules, something like:

    WARN IF Count > 0 IN SELECT METHODS WHERE
     PercentageCoverage < 100 AND
     CodeWasChanged
     ORDER BY PercentageCoverage DESC , NbLinesOfCodeCovered , NbLinesOfCodeNotCovered

  • Travis Laborde

    Great article Patrick! Now what about this twist: To see the code-coverage numbers – but just against the new/changed code.

    We have an older code base with almost no coverage. It is too late in the game to start trying to measure test coverage on it, but we’d like to measure coverage on the newly modified or added code.

  • http://codebetter.com/members/Patrick-Smacchia/default.aspx Patrick Smacchia

    >it seems a bit hacky to use “WARN”

    Yes I agree, this is a point of the product that needs to be enhanced. In the same spirit, we have also request for ‘ERROR IF’ to make the build fail.

    We are taking the time to think how to implement all these properly considering that we have a lot of plans already fixed for the future.

  • John Long

    I’ve been using this technique to send automated reports on incremental builds, and it works great. You can even include a metric view of the diffs by checking “Display selection view pic in report”. It’s very effective at getting a general idea of how important a change is and how much attention you should pay to it.

    However, it seems a bit hacky to use “WARN”. It also masks things that you may well want to really “WARN” about, particularly if you’re using NDepend in an automated process. I’m parsing the CQLResult file using XPath, and I have no easy way to differentiate between “WARN” that should “break the build” and a “WARN” that is simply informational.

    Can we get a “REPORT IF” verb?