Automated CI workflow using GitHub Actions

[maetl]

Goals

Primary objective: Launch an automated CI workflow for Calyx C#/CalyxSharp so that contributors can see direct red/green feedback on whether a pull request is safe to merge without any extra effort or needing to worry about ‘works on my machine’.

Secondary objective: Decide on a suitable build, release and publishing workflow that makes Calyx easy to use both for Unity developers and for general C# developers. Automate the parts of this workflow where it makes sense.

Workflow

Test ⇒ Build ⇒ Publish

The test process (only) should run on any pushed branch where a pull request is opened against main.

To investigate:

• After pushes/merges into main, the test ⇒ build process should run, compiling a DLL.
• Should all merges to main trigger a point release and increment the build/revision number, or should versioning be a specific manual decision by project maintainers?
• How do we handle the publish process? Build a zip file with the README and DLL, then create a GitHub release through the API? Push to NuGet using a secret token stored in the repository settings?
• How does version stamping work? Is the version number manually edited in the repo and committed? What’s the difference between PackageVersion and AssemblyVersion?
• An alternative workflow would be to only run the publish process when detecting that a versioned tag has been pushed, so use Git to handle version stamping.
• Not sure yet on the pros/cons/tradeoffs of any of this
• How does automated doc generation from code comments work in C#?

Build script

Should be configured in YAML using the GitHub-specific dotdir convention (.github/workflows/workflow.yml). Hopefully the GitHub-provided actions/setup-dotnet will be enough to get this to work

Requirements:

• Build Matrix should include .NET version(s) that are Unity compatible (and potentially the latest/current version so that we ensure there are no fowards-compatible discrepancies from targeting older versions)
• Run the tests, log their failure (this should happen automatically, but need to ensure that whatever goes to stderr and stdout has enough information to immediately see at a glance which part of the codebase or compile/test phase to look at in order to fix it)

[bentorkington]

The NuGet version doesn't have to match the Assembly*Version attributes, though obviously it's desirable that it does. The $version$ token in the NuSpec file will take the version info from the CLR Assembly Manifest preferring AssemblyInformationalVersion, and falling back to AssemblyVersion

How to use the different attributes in a SemVer way:

AssemblyVersion: only bump when making breaking changes. This is what other DLLs that link to our library will use to determine if they're compatible. If following SemVer this would only be "1.0", "2.0"… By default NuGet will only look at this if AssemblyInformationalVersion isn't defined.

AssemblyFileVersion: a version that's usually three parts of SemVer followed by one build number (even if the .net Version class calls them major.minor.build.revision). This version should uniquely identify a given DLL.

AssemblyInformationalVersion: can contain string info, such as "-beta4". NuGet will use this if it available.

https://stackoverflow.com/questions/11965924/nuspec-version-attribute-vs-assembly-version
https://stackoverflow.com/questions/64602/what-are-differences-between-assemblyversion-assemblyfileversion-and-assemblyin
https://www.xavierdecoster.com/post/2012/04/26/nuget-version-token-explained

[bentorkington]

@maetl can you please arrange for creating the NuGet account if not already done, and create an API key with

• permission to new packages and package versions
• with a glob pattern of Calyx.* (which is available) or whichever package name you'd prefer

I have a WIP branch of Github actions for running builds and tests, and publishing to NuGet that I've tested on another repo and working well.

[bentorkington]

Replacing .csproj's differing types of versioning tag with the single <Version>1.2.3</Version> might be the way here. AssemblyVersion and AssemblyFileVersion will inherit the Version value, and NuGet will use it as the package version.

[bentorkington]

• How do we handle the publish process? Build a zip file with the README and DLL, then create a GitHub release through the API? Push to NuGet using a secret token stored in the repository settings?

Both? Unity doesn't seem to be NuGet friendly and it looks like people just extract the DLL out of the .nupkg anyway, but we would otherwise want to support NuGet which is quite easy, and use Github Releases for the .dll version

[bentorkington]

• An alternative workflow would be to only run the publish process when detecting that a versioned tag has been pushed, so use Git to handle version stamping.
• Not sure yet on the pros/cons/tradeoffs of any of this

We could take the version number from a pushed tag or the .csproj file, but neither seem very single-source-of-truthy.

Perhaps a release could be marked by a merge into a release branch, which then takes the version number from the .csproj, performs the relevant build and publish actions, and creates the tag there.

[bentorkington]

• How does automated doc generation from code comments work in C#?

A .csproj flag enables generation of an XML documentation file alongside the DLL, which is enough for Intellisense to work. Tested with a .nupkg from from the project.

DotFX can generate static HTML sites out of the documentation, and a this action is available for publishing directly to Github pages.