Neovolve.CodeAnalysis.ChangeTracking 3.0.0

.NET 5.0 .NET Standard 2.1
Install-Package Neovolve.CodeAnalysis.ChangeTracking -Version 3.0.0
dotnet add package Neovolve.CodeAnalysis.ChangeTracking --version 3.0.0
<PackageReference Include="Neovolve.CodeAnalysis.ChangeTracking" Version="3.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Neovolve.CodeAnalysis.ChangeTracking --version 3.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Neovolve.CodeAnalysis.ChangeTracking, 3.0.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Neovolve.CodeAnalysis.ChangeTracking as a Cake Addin
#addin nuget:?package=Neovolve.CodeAnalysis.ChangeTracking&version=3.0.0

// Install Neovolve.CodeAnalysis.ChangeTracking as a Cake Tool
#tool nuget:?package=Neovolve.CodeAnalysis.ChangeTracking&version=3.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Neovolve.CodeAnalysis.ChangeTracking

C# code analysis tool for evaluating changes to contracts

GitHub license Nuget Nuget Actions Status

Introduction

Neovolve.CodeAnalysis.ChangeTracking is a package that calculates changes between two versions of C# code to identify what has changed in regard to Semantic Versioning. The outcome will be an overall Semantic Version change result (None, Feature, Breaking) as well as a collection of changes. Each change in the collection identifies the source and target change along with a message indicating the change and the SemVer impact of that change.

Installation

Production and beta versions are available on NuGet.

Install-Package Neovolve.CodeAnalysis.ChangeTracking

Continous Integration builds are available on MyGet.

Install-Package Neovolve.CodeAnalysis.ChangeTracking -Source https://www.myget.org/F/neovolve/api/v3/index.json

Features

This library will determine whether C# code has changed in a way that introduces a new feature or a breaking change.

Changes are evaluated for:

  • Classes
  • Interfaces
  • Structs
  • Properties
  • Fields
  • Methods
  • Attributes

The types of changes evaluated are:

  • Items removed
  • Items added
  • Items renamed
  • Changes to namespace (moved types, renamed namespace)
  • Changes of types
  • Changes to access modifiers
  • Changes to modifiers
  • Changes to generic type parameters
  • Changes to generic type constraints

Changes not currently evaluated are:

  • net5.0 record types
  • net5.0 init properties

Usage

var oldCode = new List<CodeSource>
{
    new CodeSource(@"
        public class Test
        {
            public string Value;
        }", "Test.cs")
};
var newCode = new List<CodeSource>
{
    new CodeSource(@"
        public class Test
        {
            public bool Value;
        }", "Test.cs")
};

var calculator = ChangeCalculatorFactory.BuildCalculator();

var result = await calculator.CalculateChange(oldCode, newCode).ConfigureAwait(false);

if (result.ChangeType == ChangeType.None) 
{
    // Looks like there is no change in the members
}
else if (result.ChangeType == ChangeType.Feature)
{
    // Looks like members have been added to the code
}
else if (result.ChangeType == ChangeType.Breaking)
{
    // Looks like members have been removed or changed
}

Limitations

The library evaluates code changes by parsing the code text. The advantage of this method is that the code does not need to be compiled, dependencies do not need to be resolved and any C# project usage is supported. In fact the csproj itself is not even supported as the library only parses cs files. The disadvantage is that evaluating code changes can produce false positivies because all differences are evaluated as string values.

For example, the following two code blocks when evaluated will indicate a breaking change. In reality, it is likely that the code will compile to the same outcome.

public MyNamespace
{
    public class MyClass
    {
        public System.DateTime MyValue { get; set; }
    }
}
using System;

public MyNamespace
{
    public class MyClass
    {
        public DateTime MyValue { get; set; }
    }
}

Frequently asked questions

Why does SemVerChangeType define None instead of Patch?

This package attempts to calculate the Semantic Version impact on a C# binary based on changes to the public API surface (see attribute comparison below). Adding new signatures would be calculated as a feature and removing or modifying signatures would result in a breaking change.

There are only two other scenarios that could occur between two sets of C# code. There is either no change or there is a change to internal logic where there is no impact on the public API surface. No change should not even be identified as a patch change while changes to internal logic should be a patch change. As the library does not look at internal code, it can't actually determine the difference between these two scenarios so it does not attempt to identify a patch change as this may be misleading.

Why do attribute changes identify a feature or breaking change when the public API signature hasn't changed?

There is an edge case to the idea that the library only compares the public API surface between two versions of C# code. The library also evaluates changes to attributes based on the ComparerOptions class in order to determine a Semantic Version impact of attributes.

What this means is that the C# signatures could be the same, but attribute changes regarding XML and JSON serialization could cause a potential breaking change to consumers of the library. So signatures compiled into the binary are the same, but the attributes are telling the runtime to handle serialization differently.

For example, consider this change. Here is the old code.

using System;

public MyNamespace
{
    public class MyClass
    {
        public DateTime MyValue { get; set; }
    }
}

Here is the new code.

using System;
using System.Text.Json.Serialization;

public MyNamespace
{
    [JsonPropertyName("otherValue")]
    public class MyClass
    {
        public DateTime MyValue { get; set; }
    }
}

This is a breaking change to consumers because the json serialization of this class has changed the name of the property from MyValue to otherValue.

Resources

Combinations of data sets (combinations of access modifiers for example) were calculated using https://www.mathsisfun.com/combinatorics/combinations-permutations-calculator.html.

This project is supported by JetBrains

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.1
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.0.0 280 11/6/2021
3.0.0-beta0020 150 10/4/2021
3.0.0-beta0014 162 10/3/2021
3.0.0-beta0009 128 9/18/2021
3.0.0-beta0005 192 9/12/2021
3.0.0-beta0002 200 9/12/2021
2.0.1 129 8/29/2021
2.0.1-beta0001 100 8/29/2021
2.0.0 157 8/29/2021
2.0.0-beta0325 140 8/29/2021
2.0.0-beta0288 134 7/31/2021
2.0.0-beta0252 110 4/26/2021
2.0.0-beta0217 98 4/25/2021
2.0.0-beta0183 116 4/25/2021
2.0.0-beta0150 121 4/21/2021
2.0.0-beta0118 137 4/18/2021
2.0.0-beta0087 131 4/17/2021
2.0.0-beta0057 85 4/13/2021
2.0.0-beta0028 114 2/7/2021
1.1.0-beta0123 167 11/23/2020
1.1.0-beta0101 180 11/23/2020
1.1.0-beta0080 183 11/23/2020
1.1.0-beta0060 176 11/23/2020
1.1.0-beta0041 220 11/22/2020
1.1.0-beta0023 161 11/13/2020
1.1.0-beta0022 187 11/12/2020
1.1.0-beta0021 190 11/12/2020
1.1.0-beta0020 187 11/10/2020
1.1.0-beta0019 221 10/14/2020
1.1.0-beta0018 226 10/14/2020
1.1.0-beta0017 181 10/9/2020
1.1.0-beta0016 236 10/3/2020
1.1.0-beta0015 265 9/27/2020
1.1.0-beta0014 205 9/15/2020
1.1.0-beta0013 190 9/9/2020
1.1.0-beta0012 187 9/9/2020
1.1.0-beta0011 182 9/2/2020
1.1.0-beta0010 174 8/21/2020
1.1.0-beta0006 247 8/12/2020
1.1.0-beta0003 201 8/12/2020
1.1.0-beta0001 244 8/9/2020
1.0.0 283 8/8/2020
0.1.0-beta0104 223 7/14/2020
0.1.0-beta0096 236 8/8/2020
0.1.0-beta0084 235 6/2/2020
0.1.0-beta0069 236 7/20/2020
0.1.0-beta0068 241 7/20/2020
0.1.0-beta0065 238 5/25/2020
0.1.0-beta0063 233 8/8/2020
0.1.0-beta0054 219 8/5/2020
0.1.0-beta0053 188 8/5/2020
0.1.0-beta0047 240 5/22/2020
0.1.0-beta0044 240 7/20/2020
0.1.0-beta0030 202 5/22/2020
0.1.0-beta0029 210 8/5/2020
0.1.0-beta0026 228 7/20/2020
0.1.0-beta0022 185 7/20/2020
0.1.0-beta0021 202 7/19/2020
0.1.0-beta0015 223 5/21/2020
0.1.0-beta0014 209 5/15/2020
0.1.0-beta0013 259 11/25/2019
0.1.0-beta0012 270 11/16/2019