fsprojects / syntacticversioning

Helper tool to verify semantic version changes based on API surface area changes

SyntacticVersioning

Goal

Be able to get an idea about the semantic version changes based on the surface area changes of a .net assembly.

Developers should be able to use the tool to give a magnitude of any API changes. This is helpful when pushing NuGet-packages from a continuous integration server. Internally used NuGet packages of a .net developer organisation often focus on delivering on business goals; the versioning is easily forgotten. I.e. we want to be able to use this from TeamCity and others.

When upgrading a package you want to know the magnitude of the changes. In many cases the easiest way right now is to upgrade and look at the compilation errors. Having more information directly in NuGet helps.

Integration

• You can use the SynVer.Lib found on NuGet
• In order to integrate with FAKE you can use the NuGet

Requirements

SyntacticVersioning requires a local git installation. You can download git from Git Downloads.

Maintainer(s)

• @gentauro
• @wallymathieu
• @baronfel

The default maintainer account for projects under "fsprojects" is @fsprojectsgit - F# Community Project Incubation Space (repo management)

syntacticversioning's Issues

Add @baronfel to syntactic versioning

The more the merrier!

@baronfel

Port rake script to SyntacticVersioning

Description

Port the following script to albacore ( and make sure that it's possible with SyntacticVersioning ):

https://github.com/wallymathieu/SemVer.FromAssembly#together-with-albacore-and-rake

Expected behavior

• It should be possible to write a similar script using SyntacticVersioning

Port CAKE integration for SemVer.FromAssembly to SyntacticVersioning

Description

https://github.com/wallymathieu/Cake.SemVer.FromAssembly

Copy paste the code and change it to Cake.SynVer.

Allow source to be a nuget package

Description

I'd like to be able to use a previously published nuget package instead of having a dll locally. We could solve this one a few ways.

• specifying the nuget url
• another switch type with just a name of a package and version

Known workarounds

Download the nuget package outside the tool on to your local machine

Related information

• Operating system
• Branch
• .NET Runtime, CoreCLR or Mono Version
• Performance information, links to performance testing scripts

Dependency on chiron

Description

We will take a dependency on chiron

Goals

• Be able to serialise an assembly surface area to some simple format
• Have chiron (or other simple tool) as a file reference and that module should be internal.
• Be able to diff an assembly and serialised in some simple format

Use Mono-Cecil or similar to read metadata

• In order to avoid assembly load issues (when you have for instance lots of dependencies), read binary metadata and generate simple metadata that is easy to diff

Or perhaps https://www.nuget.org/packages/ICSharpCode.Decompiler

Breaking change by changing dependency

• Whenever you upgrade / downgrade a package with a completely different signature that causes incompatibility.

How should that be detected?

Order of enum members

Description

Is the order of enum members a part of an API? For instance if you have something like:

type Enum = | Foo = 0 | Bar = 2 | Qux = 5 | Baz = 3  

that get changed to

type Enum = | Foo = 0 | Bar = 2 | Baz = 3 | Qux = 5  

Is that considered a change?

While for instance this change:

type Enum = | Baz = 3 | Foo = 0 | Bar = 2 | Qux = 5 

that get changed to

type Enum = | Foo = 0 | Bar = 2 | Baz = 3 | Qux = 5  

would change the meaning of

T temp = default(T);

Port fake script to SyntacticVersioning

Description

Port the following script:

https://github.com/wallymathieu/SemVer.FromAssembly/blob/master/SemVer.FromAssembly.FAKE.fsx

The parts that need to be ported are the following:

let bumpVersion magnitude (version:SemVerInfo)=
    match magnitude with
        | Magnitude.Major -> { version with Major=version.Major+1; Minor=0; Patch=0 }
        | Magnitude.Minor -> { version with Minor=version.Minor+1; Patch=0 }
        | Magnitude.Patch -> { version with Patch=version.Patch+1 }
        | m                -> failwithf "Unknown magnitude %s" (m.ToString())

let getMagnitude original new_=
    let maybeMagnitude = SemVer.getMagnitude original new_
    match maybeMagnitude with 
    | Result.Ok m -> m
    | Result.Error err->
        failwithf "Error: %s" err

Expected behavior

• There might be a need for a new sub library that depends on the Fake.SemVerHelper in order to have a dependency on Fake
• A script similar to the above should be possible

NuGet bump && diff

Description

Integrate the NuGet bump and diff code from @gentauro SpiseMisu.SemanticVersioning into SyntacticVersioning

Expected behavior

Should provide similar API as SpiseMisu.SemanticVersioning

Version 0.0.1 or 1.0.0 ?

Description

I accidentally uploaded two NuGet packages while pushing to NuGet. The question is if NuGet will remove the 1.0.0 version or if we should start with version 1.0.0 ?

.NET Core support

Is it possible to use the library with .NET Core? Thanks!

consider distributing as a dotnet-cli global tool

Description

First off, this tool is great and I have used it several times to solve problems related to API surface area.

I think usability-wise it would be excellent if the current binary was also packaged/shipped as a dotnet sdk global/local tool, so that users could do something like

dotnet tool install synver -g
synver bump .
// or 
synver diff dllA dllB --format json

etc. This would also allow for users adding the tool to their tool manifest so it's restored alongside other packages.

I'd be willing to do this work if you like the suggestion, but it might be a bit because I'm prepping for OpenF# at the moment.

Show how the code can be used together with tags

Description

https://github.com/libgit2/libgit2sharp/wiki/git-tag

Fix build on Windows

• Issues building on Appveyor: Start of process '/c/Program Files/dotnet/dotnet' failed
• Issues building on Windows 10 cmd prompt: Could not find executable which ...

Reuse code from SemVer.FromAssembly to create standalone exe

Description

The code from:

https://github.com/wallymathieu/SemVer.FromAssembly/compare/syntactic_versioning?expand=1

can probably form a basis for a standalone tool

Inheriting from interfaces

Description

When you add an interface is possibly a minor change. While removing an interface is probably a major change.