## Blog: Ramón Soto Mathiesen

This post is part of the F# Advent Calendar in English 2016. Please check out the other posts as well.

I would also like to thank Scott Wlaschin for his willingness to make an e-book with the posts and raise money for a good cause: Tweet. Be sure to contribute with this cause (retweet and economically).

### Background

It should be no secret that I’m a big fan of Elm and it shouldn’t be no secret as well that I have been working with F# for a long time and is still a bit of a fanboy.

One of the features that is missed the most when jumping between these two fantastic languages is the Semantic Versioning to handle package versions from Elm (bump and diff).

In this blog post I will argue that I have made a .NET library (very early in development stage but almost complete, you folks will decide) that will be able to help you out whenever you have to decide if a new version of your Assembly or NuGet package is a Major, Minor or just a Patch (Major.Minor.Patch).

### Semantic Versioning

So what is Semantic Versioning (SemVer)? If we look into the following website: semver.org, we can read statements like:

• In the world of software management there exists a dread place called “dependency hell”.

• The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself in it.

• If dependencies are specified too loosely, you will probably end up breaking your build more than desired.

In the mentioned website there are described 12 rules, to be enforced by documentation or the code itself, to solve the issue but we will stay with the following summary:

• … given a version number (MAJOR.MINOR.PATCH), increment the:

• MAJOR version when you make incompatible API changes,

• MINOR version when you add functionality in a backwards-compatible manner, and

• PATCH version when you make backwards-compatible bug fixes

And that is pretty much it.

Note: I have removed the word documentation, as I am in the belief that this task should be done automatically by a computer and not by a human. In a similar way as a computer help us catch errors at compile time instead of end-users at runtime.

### elm-package bump and diff

If we look into Elm’s tool for package publishing, called elm-package, it has two main actions which are related to SemVer: bump and diff

#### elm-package bump

As we can see from the GitHub repository of the tool, the version rules as very similar to the ones we just described in the previous section:

• Versions all have exactly three parts: MAJOR.MINOR.PATCH

• Versions are incremented based on how the API changes:
• PATCH - the API is the same, no risk of breaking code ✓
• MINOR - values have been added, existing values are unchanged ✓
• MAJOR - existing values have been changed or removed ✓
• elm-package will bump versions for you, automatically enforcing these rules ✓✓✓

Note: You can’t actually publish a package without running the bump action first.

#### elm-package diff

The previous action, bump is really good to tell the hole world (broadcast) the changes you have done to your library, while, diff, is great for a consumer of a library to actually see which changes have been made and if they are actually going to have an impact on the library they are developing. Example, if changes are done to some data structures I’m not using, I would probably be able to just upgrade to the newer version without having to refactor any code:

#### Rust and others

Other languages have been looking into SemVer as well:

• Rust (suggestion for cargo):
• Haskell (why does cabal or stack not have this?):

I think we all have tried to use a given package that failed to install due to issues with dependent packages right? Frustration, most of the time, tend to dropping a given package and sometimes even moving on to other languages …

### SpiseMisu.SemanticVersioning library

Here is my proposal of SemVer for .NET libraries as well as for NuGet packages

Note: I support both C#/F# (VB? I’m not the right guy to do this task …)

As with Elm, I would like the rules to be enforcement by the code itself, instead of by humans. Otherwise we would be back to square one as humans tend to fail with repetitive task and when the library becomes of a considerable size, the task will become unmanageable.

Elm has it easy as everything is Open Source, therefore source code can be parsed while with .NET (proprietary libraries) we will have to fallback to handle this task just like Unit Tests are handled in Fsharp.Core with Reflection:

There is a bit more to it as the main issue with basic Reflection, is that it works great with C# libraries, but not so much with F#. The following functions signatures are represented on the same way in .NET canonical form (no curried arguments):

Therefore we need to have in mind a few other cases such as Product Types, Modules and even Enums & Sum Types (due to pattern matching) that needs to be handled in a special way:

• Cases like Active/Partial Patterns and MeasureOfUnits are not handled (yet? Is it even necessary?).

• Please look into the Open Source code to see what is done for each cases.

The main goal is to create a bijective function that would replace the non-injective and surjective function which will ensure that a given input value will always have a unique output value. Think of it as a perfect hash function with no collisions.

I’m also becoming really keen to Haskell and Elm signatures readability, where the last type is the return type of the function while the others are input parameters. Example:

This is also the reason why I have begun to write F# code like this:

And therefore I’m aiming to produce output that comply with these signatures.

Note: The learning curve for F# would be non-existent as we already see this kind of signatures when evaluating with F# Interactive but it might be hard, at the beginning, to read for the C# Community, but they probably get used to it.

As mentioned in the title, I’m aiming to support both Assemblies and NuGet packages:

• .NET Library (Assembly): Is usually a single file compiled to target a specific version of the .NET Framework. Example:
• .NET NuGet package: Is a unit of distribution containing some metadata as well as binaries. In most cases, there are binaries targeting several versions of the .NET Framework. We are only interested in libraries (lib/…/???.dll)

Here are a few examples on the usage of the library:

#### .NET NuGet package

Output Gist SpiseMisu.NuGet.SemVer.md

#### .NET Library (Assembly)

Output Gist SpiseMisu.Assembly.SemVer.md

#### .NET Library (documentation)

Output Gist SpiseMisu.Docs.SemVer.md

Note: A side-effect of the code is that I was actually able to document the hole public API of a given library. Therefore I thought that I would just expose this logic, this was not intentional.

#### .NET Library (raw)

Output Gist SpiseMisu.Raw.SemVer.txt

Note: I have decided that my output should be of the type of Markdown, if other should differ from this opinion, they can just work with the raw data and produce their own.

### Trivial Pursuit

Just to have an understanding of what is going on under the hood. Lets take a look at the following example code:

#### Enum3.cs

which is compiled with Mono producing .NET assemblies.

We will now compare the Enum.cs vs Enum2.cs and Enum.cs vs Enum3.cs

What is the outcome that you expect?

Output Gist SpiseMisu.Talk.SemVer.md

If you guessed that it should be a MAJOR update in both cases, then you are actually right. I’m one of those guys that always compile my F# code with the following flag: –warnaserror:25 to ensure that all patterns are covered. Therefore, if you add a new value to Enums and Sum Types, this should state that is a MAJOR update and you should probably revise your code to handle the newly added patterns.

### What’s next?

I have given a talk on this matter at MF#K where we had an interesting discussion (a few feature addition were requested). I will see how fast I can make these changes and finalize the project, based on Project Scaffold, and then I will release the library as Open Source @ GitHub.

When the code is publicly available, I would RFC from the .NET Community, specially experts in the subject, to review the code.

Note: Have in mind, that I’m not using the F# Compiler Services as I’m aiming for a very lightweight library with as few dependencies as possible

The outcome I desire for this library is that it gets integrated with:

• NuGet: Or something similar, please steal with pride. The goal is that we get this awesome feature and not so much that it was me who did it.

• FAKE: This is one of the reasons I produce Markdown output as it is possible to just pipe the result of bump and diff to the top of the RELEASE_NOTES.md to automate the generation of this document, as it sometimes can be a bit tedious and boring.

• Paket: This would be optional, but because this tool already has NuGet package publishing capabilities, therefore it would give sense to add the bump and diff functionality.

Last, but not least, in order to catch on with the C# Community, I guess that we will need a standalone executable (something like paket.exe) which is totally transparent with regard of it’s F# nature, as we all know some .NET people are allergic to the this amazing programming language. I’m thinking about using for this task:

### Conclusion:

I hope I’ve convinced you of why SemVer enforced by code is so awesome.

I’m also hopping that you can agree that the presented library:

• Supports .NET Assemblies and NuGet packages as well as C# and F# (even proprietary due to Reflection).

• SemVer rules are also enforced by the code itself, just like elm-package.

• The produced Markdown output is easily readable.

As I mentioned before, I gave a talk on the subject at the F#unctional Copenhageners Meetup Group where we had a really constructive discussion with different points. One of the main points, delivered by Ulrik Rasmussen was that Semantic Versioning shouldn’t be called that in the first place, but instead it should be called Syntactic Versioning as we are only able to see if a dependencies break when signatures change (syntax) and not if the behavior (semantics) change. Let’s look into a simple example where we just refactor our foo function from fold left with right:

Syntactically the signatures are the same, but the semantics of the application aren’t.

That said, I think the intentions of Tom Preston-Werner was to keep the dependency hell to a minimum as well as limiting the amount of builds breaking. As with everything else, there is really no silver bullet to solve all our problems at once, but we should strive to achieve it though:

Perfection is not attainable, but if we chase perfection we can catch excellence” –Vince Lombardi

### References:

• Technology at GDS’s Blog:

### References:

• David Raab’s blog:

### Background

This seems a topic that keeps showing up again and again. After every MF#K Meetup last Tuesday of every month we always go out for a couple of beers and speak heavily in favor of the language that we like the most. There are people who seem to need types to code, I will include myself in this group, while others seem to do fine with languages without types as for example Clojure, Erlang, Elixir, … My former workmate, Brandon Lucas, keeps trolling on how you can’t model a state-machine with types, and until I wrote this post, I would totally agree.

What you normally see in blog post when this topic is explained is something similar to this (I will draw some ASCII art to give a better understanding):

What is represented here is a state machine for a light switch. The state is defined as a sum type (algebraic data type) of the two values it can be. But, then when you need to perform the state transition, you would see how people fallback to a function to handle this logic.

In my example, I have deliberately introduced a bug in the transition function just to prove why this approach is problematic.

This is one of the misconceptions that you hear people talking about when they make the transition to functional programming languages. They think just because they have modeled the domain with a few sum and product types (algebraic data types) it’s all good and you can then claim absolute sentences like: “Make illegal states unrepresentable” and “Making Impossible States Impossible” and therefore you probably don’t need to test that part of the code, which is obviously a wrong misconception of what the authors tries to point out.

We need to be very thoughtful (and mostly careful) when we make those kind of statements, specially due to the audiences that might receive (conceive) these messages.

Note: I’m not dishing neither “Yaron Minsky” nor “Richard Feldman” as I have a HUGE respect for both on their work on OCaml and Elm respectively.

### Use the type system instead of functions

So how can we move the logic from the function into the type domain by using the type system?

Well firstly we will need to introduce the following three simple concepts:

1. Phantom Types: Are parametrised types whose parameters do not all appear on the right-hand side of its definition. Example: type 'a Foo = Bar.

2. Function Types: Define a function signature as a type. Example for the identity function: type 'a Id = 'a -> 'a.

3. Not accessible Sum Type Case Constructors: By hiding the underlying case constructors for a given sum type, you can ensure that only specific parts of the code can instantiate your type. Example: type FooBar = private | Foo of int | Bar of float

Lets see how I use them to re-model the light switch state machine:

We combine the concepts 1. and 3. to define the State type, which we limit to only two states: TurnedOn and TurnedOff, which also requires to introduce two type terms: On and Off.

Finally, we just need to expand our domain with the transition types, which we can use concept 2. to create two transition states: TurnOn and TurnOff, which will subsequently require to have the opposite state as input parameter.

That’s it. Now our domain model contains all the logic while our functions just are pure interfaces with no logic whatsoever, see both helper functions, for the initXXX and turnXXX functions. The functions just return the internal State type, which gets tagged by the type definitions. Pretty nifty right?

And we can be sure that no invalid State is created because we ensured that it can’t be instantiated from outside the module (and sub modules). So even though type 'a Switch is a generic type, we have limited only to the two states mentioned before.

The only minor issue is that type abbreviation (alias) in F# are erased at compile time and therefore not available at runtime, as Marcus Griep points out in the following tweet, therefore it’s a bit more difficult to output the currently state (see in next coding blocks how this can be overcome).

### Demo:

So lets see how its used:

Produces the following output:

A bit more complex example where we just want to automate the switch to turn on/off a couple of times in a row. To be able to do this, we introduce the Either sum type for better readability, but the built-in Choice<'a,'b> F# type could be used as well. This construct will also allow us to make a better output printer than the one that is based on .NET Reflection as we have a guarantee of which types go in to the Left and Right wrappers.

### Conclusion:

I hope I can convince others that it is possible to model a state machine exclusively by using the type system, while keeping the logic out of the function layer. It uses a few type tricks that are present in F# but probably also in other ML alike languages.

Note: Don’t forget to ALWAYS use FsCheck, F# implementation of Haskells QuickCheck, even if you use this kind of approach. We are all human and therefore can fail. If you just remember this last part, You would make me a happy person.

• Wikipedia: