Document upgrade path from 1.x of Cake.Recipe to 2.x

[gep13]

There are lots of breaking changes, and new features, so we need to provide some information to folks so that they know what to expect if upgrading.

Starting a list of things that need to be changed, there will likely be other things that need to be added:

• Change Cake.Recipe pre-processor directive to use latest version
• Pin to updated version of Cake - 0.38.4
• Remove input parameters which are no longer required, for example shouldRunGitVersion: true as this is now the default
• Update bootstrapper to include --bootstrap command
• Project is using an embedded icon
• Project is using a deterministic build - --target=Enable-DeterministicBuild
• Rename AppVeyor default target - AppVeyor -> CI
• Update GitVersion.yml file with the required changes for using new version of GitVersion
• Add CakeContrib.Guidelines Nuget Package and add PackageIcon to csproj
• Remove usage of nuspec file(s) for NuGet packages, instead, we will run DotNetCore-Pack
• Add shouldUseDeterministicBuilds: true parameter
• Check for usage of shouldRunCodecov: true which is not required anymore - this is new default
• Add Cake.Addin.Analyzer package
• Add settings.json file for VSCode
• Add dependabot config file
• Add GitHub Actions
• Switch to Cake.Tool rather than Cake.exe
• Switch to not running PR's on AppVeyor
• Check for trailing spaces in the TestCoverageFilter
• Ensure targeting netstandard2.0 for project and netcoreapp2.1 and netcoreapp3.1 for tests
• Ensure AppVeyor build image is using latest
• Fix broken unit tests
• Fix dupFinderExcludePattern for multi-targetting platforms
• Update bootstrappers to use .Net Global Tool
• Update appveyor.yml file to bust cache based on change to only the recipe.cake file, since we are deleting the packages.config file
• Delete packages.config file
• Update .gitignore file to no longer exclude the packages.config file
• Ensure that Environment.SetVariableNames() is called in recipe.cake file

[AdmiringWorm]

@gep13 maybe linking to the gist you created on Monday could be useful as well.

Or we could just move those here to this issue?

[gep13]

@AdmiringWorm good idea, I have updated the issue description with some of the items that I have, but we can add more as we think of them

[nils-a]

@gep13 I followed this instructions at cake-contrib/Cake.7zip#62 - and it worked like a charm.

However, I kind of "miss" some guidelines on how to procede with the two build-services (i.e. appveyor / gh-actions): Some steps of the processes (e.g. publishing docs/nupkg etc) should only run once, right? How can we configure which buildsystem is doing what?

As an example, I can imagine some obscure config like:

• Building, running test etc would be done on all systems
• publishing docs is only done from the gh-actions
• publishing to myget (I know, it's broken...) from appveyor
• publishing to azure-feed from azure devops

[AdmiringWorm]

Building, running test etc would be done on all systems

This is done on all platforms already.

You unfortunately can't select only a few tasks to run on specific providers, only on the global stage.
Either all tasks will will be tried on appveyor, or all on github actions (by setting the preferredBuildProviderType and optionally preferredBuildAgentOperatingSystem).
More fine-grained control of the tasks is on my radar, but due to what would be necessary to change it is probably something that won't happen until 3.x.

Side-Note, forcing publishing and drafting release notes will always run when called.
These are not specifically tied to any provider.

[gep13]

@AdmiringWorm said...
More fine-grained control of the tasks is on my radar, but due to what would be necessary to change it is probably something that won't happen until 3.x.

Agreed

[gep13]

@nils-a said...
followed this instructions at cake-contrib/Cake.7zip#62 - and it worked like a charm.

This is great to hear! Thank you for providing feedback!

@nils-a said...
However, I kind of "miss" some guidelines on how to procede with the two build-services

Based on what @AdmiringWorm has said, do you think we need some more information in the docs for Cake.Recipe? If so, would you be in a position to take a stab at adding that?

[AdmiringWorm]

Just to follow up on what I said.
If you wish only to run certain tasks on a build provider, you would need to modify the criteria used for those tasks.

That would mean to clear all the criteria of the task, then add the existing ones again (except those related to build platform and build provider), then add a new criteria that compares the build platform and provider.

For instance as an example,
if wanting to run the documentation publishing automatically when running on GitHub Actions, but everything else on AppVeyor, then the task would need to be modified with something along the lines of:

((CakeTask)BuildParameters.Tasks.PublishDocumentationTask.Task).Criterias.Clear();

BuildParameters.Tasks.PublishDocumentationTask
	.WithCriteria(() => !BuildParameters.IsLocalBuild)
    .WithCriteria(() => !BuildParameters.IsPullRequest)
    .WithCriteria(() => BuildParameters.IsMainRepository)
	.WithCriteria(() => BuildParameters.BranchType == BranchType.Master || BuildParameters.BranchType == BranchType.Develop)
	.WithCriteria(() => BuildParameters.PreferredBuildAgentOperatingSystem == PlatformFamily.Windows)
	.WithCriteria(() => BuildParameters.PreferredBuildProviderType == BuildProviderType.GitHubActions);

This is something you would need to do for all tasks you want to override the criterias.

DISCLAIMER: The above code sample has not been tested, and is mostly just taken from memory.

[nils-a]

@AdmiringWorm thanks for the hint. I'd rather not create a setup like I laid out above (too unstructured). I can, however envision a setup in which all is done in one system (gh-actions) except uploading preview/dev packages to azure feeds - that would be done using a devops pipeline...

@gep13 I'l take a shot at it. I'm thinking about a section on ci-systems (which are "supported"/"tested", which quirks exist.) I feel that would also be a good place to describe the setup involved when dealing with multiple ci-systems.

[gep13]

@nils-a that would be great! I think that sounds like a great approach!

[nils-a]

New point: my .appveyor.yaml contains:

cache:
  - "tools -> recipe.cake,tools/packages.config"

after switching from cake.exe to cake.tool, shouldn't that be

cache:
  - "tools -> recipe.cake,.config/dotnet-tools.json"

[gep13]

@nils-a Yes, that is a good catch!

[gep13]

@nils-a I have updated the original issue description with this point. Let me know if you find any others.

[nils-a]

@gep13

• Delete packages.config file

good point. While I did that on cake.7zip, I did not realize, that it's not on the list.
Also, after removing tools/packages.config, probably there is also an entry for in .gitignore. (There was one in my .gitignore..)

[AdmiringWorm]

Another new thing I found while migrating the Cake.Transifex addin to the latest Cake.Recipe version.

If you do not already call Environment.SetVariableNames(), then this must be added to the cake script before calling BuildParameters.SetParameters.
This is something that was optional in v1.x (at least I never added it to the build script in that repo).

[gep13]

@AdmiringWorm thanks for catching that! I have added it to the list. Did this show up as an error when trying to run the build?

[AdmiringWorm]

yes, it shows up as a null reference exception when building.

[AdmiringWorm]

To be more specific, this is the error message that comes up (with normal verbosity).

[AdmiringWorm]

Recommendation of what setting to enable when disabling pull request builds on appveyor:

[nils-a]

@gep13 as discussed on stream last night, the point

• Update appveyor.yml file to bust cache based on change to .net global tool json file, rather than packages.config file

should be phrased different, since we're only removing packages.config and not add dotnet-tools.json

[gep13]

@nils-a I am not sure that I follow. I thought that the suggestion going forward was to switch to using a tool manifest, and to restore and run dotnet cake. As such, the packages.config file is not needed, and instead, we should bust the cache based on changes to the manifest file, or the recipe.cake file.

[nils-a]

but changes to the dotnet-tools.json do not result in changes to the tools-folder (global tools are restored somewhere else) so there's no need to bust cache on the tools-folder, if dotnet-tools.json changes.

[gep13]

Ah, I see what you mean now, makes sense.

[nils-a]

I ran into a new issue (should pay more attention to appveyor) not sure if documentation is needed, though.

My old appveyor.yaml stated .\build.ps1 -Target AppVeyor which I dutifully changed to .\build.ps1 -Target CI..

However, the new minimalistc bootstrapper I am using does not (like the official one does) "translate" the PowerShell-Syntax arguments. So, long story short: .\build.ps1 -Target CI does not work. .\build.ps1 --target=CI is needed.