In the 2.0.0 release of Cake.Recipe, there were a total of 15 breaking changes. As a result, there are a number of changes that have to be made to any project that is currently using a 1.x.x release of Cake.Recipe, in order to allow it to start using this release.
Have a look at this pull request on the Cake.DotNetVersionDetector repository for an example of a project that has made this transition.
Required Changes
Stop using username and password combination for accessing GitHub
As of November 2020, GitHub is no longer going to support using a combination of username/password for accessing its API. Instead, you have to use a Personal Access Token. As a result, the ability to provide a username/password via environment variables into Cake.Recipe has been removed. Going forward, you will have to provide an environment variable for the GITHUB_PAT.
Remove input parameters which are no longer required
Input parameters for the SetParameters have changed. For example the shouldRunGitVersion parameter is now called shouldCalculateVersion.
In addition, the default values of some parameters have changed, which means that they don't need to be explicitly set. For example, shouldRunCodecov is now enabled by default.
Change Cake.Recipe pre-processor directive to use the latest version
The entry pre-processor directive should be changed to the following:
#load nuget:?package=Cake.Recipe&version=2.0.0
Pin to updated version of Cake
Cake.Recipe 1.x.x was pinned to run against version 0.32.1 of Cake. In order to use Cake.Recipe 2.0.0 you will need to use at least 0.38.4.
Update bootstrapper to include --bootstrap command
Cake.Recipe now includes the use of the .Net Global Tool Module. As such, it will be necessary to first bootstrap this module before executing the build. That can be done as follows:
Write-Host "Bootstrapping Cake"
dotnet cake $SCRIPT_NAME --bootstrap
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host "Running Build"
dotnet cake $SCRIPT_NAME @args
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Rename AppVeyor default target
Due to the fact that Cake.Recipe is no longer directly coupled to AppVeyor, the entry target name has changed. Instead of calling:
build_script:
- ps: .\build.ps1 -Target AppVeyor
you should call:
build_script:
- ps: .\build.ps1 --target=CI
Update GitVersion.yml file with the required changes for using new version of GitVersion
Cake.Recipe has switched from using 3.6.5 of GitVersion, to 5.0.1 of the .Net Framework version, and 5.3.7 of the .Net Global Tool version. There have been a number of breaking changes in how GitVersion configuration works, specifically around how branches are configured. If you have done any branch configuration in the GitVersion.yml file, you may have to update to the latest standards.
Ensure AppVeyor build image is using the latest
In order to execute correctly on AppVeyor, you will need to use the Visual Studio 2019 build image. Change the image definition from:
image: Visual Studio 2017
to:
image: Visual Studio 2019
Ensure that Environment.SetVariableNames() is called
Previously, the call to Environment.SetVariableNames was not mandatory, and could be omitted from the recipe.cake file. This is no longer the case, and it must be included.
Suggested Changes
Use embedded icon for NuGet package
This guidance comes from the NuGet team directly. From now on, you should look to include an icon within the nupkg file.
Add CakeContrib.Guidelines Nuget Package
To help with the above suggestion, and likely others given time, we are recommending that you add the CakeContrib.Guidelines NuGet package to your project. This will inspect your project, and make sure that you are following the guidelines from the Cake-Contrib Organisation for your addin.
Remove usage of nuspec file(s) for NuGet packages
Due to the fact that Cake.Recipe has now enabled fully deterministic builds by default, as well as turning on of SourceLink and embedding pdb files into the generated nupkg file, it is simply easier to run dotnet pack, rather than attempting to do this manually using a nuspec file.
To facilitate this, you will need to add the following parameter:
shouldRunDotNetCorePack: true
Add Cake.Addin.Analyzer package
Similar to the CakeContrib.Guidelines NuGet Package, we are also recommending that you add the Cake.Addin.Analyzer package to your project. This will check through your projects and ensure that you are following best practices from a Cake perspective.
Add settings.json file for VSCode
To help with ensuring consistency of an addins codebase, the following settings.json file is recommended:
{
"omnisharp.enableEditorConfigSupport": true,
"omnisharp.enableRoslynAnalyzers": true,
"[powershell]": {
"files.encoding": "utf8bom"
},
"powershell.codeFormatting.addWhitespaceAroundPipe": true
}
Add dependabot config file
To keep your dependencies up to date, we recommend that you enable dependabot to help with that task. This can be done by creating a .github/dependabot.yml file in your project with the following contents.
NOTE: If you choose to do this, we also recommend that you enable the Do not build on "Pull request" events within the AppVeyor project settings. This will prevent AppVeyor from getting overwhelmed with pull requests coming from the Cake-Contrib organisation. Enabling Do not build on "Pull request events` is only recommended if you choose to enable GitHub Actions for your project.
version: 2
updates:
- package-ecosystem: "nuget"
directory: "/"
schedule:
interval: "daily"
ignore:
- "Cake.Core"
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
Add GitHub Actions
Now that Cake.Recipe supports other platforms than just AppVeyor, we recommend adding builds for some other platforms, to allow building of addin project on all major operating systems. Details on how this can be achieved can do found in the docs.
Switch to Cake.Tool rather than Cake.exe
Since Cake.Recipe now fully supports running on .Net Core, we are also recommending that you switch to use the .Net Global Tool version of Cake. This includes using a .config/dotnet-tools.json file to pin to a specific version of Cake. More information on switching to this can be found in the Cake docs.
Update bootstrappers to use .Net Global Tool
An example of a build.ps1 file that can be used is:
$ErrorActionPreference = 'Stop'
$SCRIPT_NAME = "recipe.cake"
Write-Host "Restoring .NET Core tools"
dotnet tool restore
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host "Bootstrapping Cake"
dotnet cake $SCRIPT_NAME --bootstrap
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Write-Host "Running Build"
dotnet cake $SCRIPT_NAME @args
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
An example of a build.sh file that can be used is:
#!/bin/bash
SCRIPT_NAME="recipe.cake"
echo "Restoring .NET Core tools"
dotnet tool restore
echo "Bootstrapping Cake"
dotnet cake $SCRIPT_NAME --bootstrap
echo "Running Build"
dotnet cake $SCRIPT_NAME "$@"
Update appveyor.yml file for busting cache
On AppVeyor, it is possible to cache the contents of the tools folder between build executions. Previously, this cache would have been busted using:
- tools -> recipe.cake, tools/packages.config
However, now that the packages.config file is no longer being used, and the tool manifest does not store any tools in the repository, it can be changed to:
- tools -> recipe.cake
Delete packages.config file
Since we are recommending switching to using the .Net Global Tool version of Cake, with associated bootstrappers, the packages.config file in the tools folder is no longer required, and can be deleted. In addition, you should update the .gitignore file to remove the special handling of this file.
Ensure there are no trailing spaces in the recipe.cake file for the testCoverageFilter parameter
If there is, you might see an error like the following:
Error: One or more errors occurred. (Index was outside the bounds of the array.)
To fix this issue, simply delete the trailing space in the parameter.