jondot / nchurn

.Net based churn analyzer for your build

NChurn

NChurn is a utility that helps asses the churn level of your files in your repository.
Churn can help you detect which files are changed the most in their life time. This helps identify potential bug hives, and improper design.
The best thing to do is to plug NChurn into your build process and store history of each run. Then, you can plot the evolution of your repository's churn.
Developers see note about building below, if you want to build from source.

NChurn currently supports file-level churns for

• Git
• Hg (Mercurial)
• SVN
• TFS (Team Foundation)

As outputs, NChurn supports

• Table (plain ASCII)
• CSV
• XML (recommended for builds)
• HTML - see XSLT in /extras/build. Using XSLT you can integrate and produce HTML in your CI environment.

Amongst others, NChurn can also take top # of items to display, cut off churn level, and a date to go back up to. See "Getting Started".

Background

From this work http://research.microsoft.com/apps/pubs/default.aspx?id=69126

Code is not static; it evolves over time to meet new requirements. The way code
evolved in the past can be used to predict its evolution in the future. In particular,
there is an often accepted notion that code that changes a lot is of lower quality—
and thus more defect-prone than unchanged code.

Key Points
- The more a component has changed (churned), the more likely it is to have
  defects.
Code churn measures can be used to predict defect-prone components.

NChurn currently gives a view of file churn and will hopefully expand into analyzing files and languages themselves in the future.

Getting Started

$ NChurn -h
 NChurn 0.4.0.0
 Usage: NChurn
     NChurn -c 4 -d 24-3-2010 -t 10

 d, from-date    Past date to calculate churn from. Absolute in dd-mm-yyyy or number of days back from now.

 c, churn        Minimal churn. Specify either a number for minimum, or float for precent.

 t, top          Return this number of top records.

 r, report       Type of report to output. Use one of: table (default), xml, csv

 a, adapter      Use a specific versioning adapter. Use one of: auto (default), git, tf, svn, hg

 p, env-path     Add to PATH. i.e. for svn.exe you might add "c:\tools". Can add multiple with ;.

  i, input        Get input from a file instead of running a versioning system. Must specify correct adapter via -a.

 x, exclude      Exclude resources matching this regular expression

 n, include      Include resources matching this regular expression

 help            Dispaly this help screen.

Any combination of parameters work.

$ NChurn -t 5 -c 3        # take top 5, cut off at level 3 and below.
$ NChurn -c 0.3           # display files that consist 30% of all changes (0.3)
$ NChurn -d 24-12-2010    # calculate for 24th of Dec, 2010 up to now.
$ NChurn -c 2 -r xml      # cut off at 2, report output as XML.
$ NChurn -d 30 -i svn.log -a svn    # go back 30 days, read from pre-made file, adapter is SVN.
$ NChurn -p c:\tools\svn -a svn     # specify path and adapter on an environment that hasn't got a PATH.
$ NChurn -x exe$                    # exclude resources that end with 'exe' 

Here is a sample of a run, which cuts off at 8, and uses the default table report:

$ NChurn -c 8
+--------------------------------------------------+
| lib/rubikon/application/instance_methods.rb | 48 |
| lib/rubikon/application.rb                  | 30 |
| test/test.rb                                | 30 |
| lib/rubikon/command.rb                      | 28 |
| lib/rubikon/parameter.rb                    | 17 |
| test/application_tests.rb                   | 14 |
| Rakefile                                    | 13 |
| lib/rubikon/application/dsl_methods.rb      | 12 |
| README.md                                   | 11 |
| samples/helloworld/hello_world.rb           | 11 |
| lib/rubikon.rb                              | 10 |
| lib/rubikon/exceptions.rb                   | 10 |
| lib/rubikon/flag.rb                         | 10 |
| lib/rubikon/action.rb                       | 9  |
| lib/rubikon/application/base.rb             | 9  |
| lib/rubikon/option.rb                       | 9  |
| lib/rubikon/progress_bar.rb                 | 9  |
| samples/helloworld.rb                       | 9  |
+--------------------------------------------------+

And here is an example of taking the top 4 records on NChurn's git repo, output as xml report.

$ NChurn -t 4 -r xml
<?xml version="1.0" encoding="utf-8"?>
<NChurnAnalysisResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <FileChurns>
    <FileChurn>
      <File>README.md</File>
      <Value>2</Value>
    </FileChurn>
    <FileChurn>
      <File>.gitignore</File>
      <Value>1</Value>
    </FileChurn>
    <FileChurn>
      <File>AssemblyInfo.cs</File>
      <Value>1</Value>
    </FileChurn>
    <FileChurn>
      <File>Gemfile</File>
      <Value>1</Value>
    </FileChurn>
  </FileChurns>
</NChurnAnalysisResult>

Building

You can build NChurn in 2 ways:

• Visual studio
• Rake (albacore)

To build with rake (the recommended way), make sure to bundle install, then look at your options with rake -T.
Note: I've excluded tf.log and tf.log.result from the repository, out of discreteness. Make sure to exclude from project or even better contribute back a log we can publicly use.

Contribute

NChurn is an open-source project. Therefore you are free to help improving it. There are several ways of contributing to NChurn's development:

• Build apps using NChurn and spread the word.
• Bug and features using the issue tracker.
• Submit patches fixing bugs and implementing new functionality.
• Create an NChurn fork on GitHub and start hacking. Extra points for using GitHubs pull requests and feature branches.

License

This code is free software; you can redistribute it and/or modify it under the terms of the Apache License. See LICENSE.txt.

Copyright

Copyright (c) 2011, Dotan Nahum [email protected]

nchurn's Issues

Hg support

sample XSLT for reporting

Provide a sample XSLT for report processing into the build.
Useful for CC.NET for example.
Something to have and also start off from.

support exclude and include filters

support exclusion and inclusion of files by a file filter.
a sketch for this would be

nchurn -i .cs;.csproj -x *foo.cs

perhaps support a general regex pattern instead, for inclusion and exclusion such as

nchurn -ir ^foo\s.cs$ -xr ^goo.cs$

(this ensures hit in performance)

specify relative date

3 days ago, 2 months ago.

path to svn.exe

It would be nice if the path to svn.exe could be set via a commandline argument. In all my projects svn is bundled with the source and no installation is needed on de development machine or on the buildserver. On the development machines TortoiseSVN is installed.

I think it can be usefull for HG, Git en TFS users also.

Dependency issues with bundler. Gem found in multiple source locations.

When doing a bundle install on the master branch.

Warning: this Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source. To upgrade this warning to an error, run `bundle config disable_multisource true`.

Warning: the gem 'version_bumper' was found in multiple sources.
Installed from: http://gemcutter.org/
Also found in:
  * http://rubygems.org/
You should add a source requirement to restrict this gem to your preferred source.
For example:
    gem 'version_bumper', :source => 'http://gemcutter.org/'
Then uninstall the gem 'version_bumper' (or delete all bundled gems) and then install again.

This issue is fixed by deleting the line in the gemfile that reads
source 'http://gemcutter.org'

Ability to run analysis against existing log in a file

Querying SVN for 3years data is quite long. I'd like to get verbose log once and then analyse it in various ways.

specify cut-off by precentage

nchurn -c 30% will only show top 30 percent of all results, regardless of churn level.