Export public API to C# text files and fail unit test if not matching

[jonorossi]

For quite some time I've wanted to be able to see (and verify) public API changes as we make them, and easy see what APIs we need to mark obsolete and then remove.

This is related to #389.

I wanted something like the ref directory in .NET Standard and .NET Core that hold their reference assembly's source code (their built tools aren't (EDIT) meant to be used outside their build process), but I found the FakeItEasy guys have been doing this for quite some time, and they are using PublicApiGenerator to do it (the ApiApprover part is marked obsolete).

I wanted these files to be more obvious as something we care about (a bit like a public contract) and followed the ref directory convention, however realised they aren't really reference assemblies since we never build them, however not sure that matters much, but I'd prefer them out in front rather than hidden in a unit test project directory, so happy to hear suggestions on a different naming convention.

What are people's thoughts on this whole thing in general?

[jonorossi]

I should have mentioned the workflow:

• As a developer you run the unit tests and it'll overwrite all the .cs files in the ref directory for you
• The build server (CI=true env var) will compare the built assemblies to the files on disk, the assertion will obviously fail if someone changes the public API without also including the change to the ref/*.cs files

[stakx]

and followed the ref directory convention, however realised they aren't really reference assemblies since we never build them [...].

That probably doesn't matter much. The difference to, say, dotnet/corefx, doesn't seem all that great: As far as I know, their reference assembly sources are also generated from an assembly, and not the other way around. They just use a different tool (GenAPI) and a different source assembly (an actual reference assembly) from which the public contract is derived.

If it's important to you that the ref/ directory actually reflects a real reference assembly, we could easily build such a one using an up-to-date Roslyn compiler. I believe they added a compiler switch for that sometime earlier during the C# 7.x timeline.

Or, we could also put the public contracts in an api/ directory.

I think we should simply go with ref/ as it's an established and well-understood convention. And because we don't actually distribute reference assemblies, I don't see how any harm can come of it.

[jonorossi]

I've got no desire to actually build a reference assembly, so happy to continue with what we've got. The approval process (mentally reminding you of public API changes) is what I'm mostly after, which then also makes it easy for us to trim down the public API which contains so much cruft that is holding us back.

There is a .NET Core Global Tool beta just released, not sure it fits exactly what we are doing here, but we may be able to move to that later: PublicApiGenerator/PublicApiGenerator#55

I've rebased on master.