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

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.

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.