(cake-contribGH-612) added a section on non-local build providers (ca…

…lled CI-systems here), specifically pointing out that one provider/os-combination has to be marked "primus inter pares" using preferredBuildProviderType / preferredBuildAgentOperatingSystem. Also started on documenting the different (non-local) build providers.

docs/input/docs/ci-systems/appveyor.md

@@ -0,0 +1,37 @@
+---
+Order: 20
+Title: AppVeyor
+Description: Running on AppVeyor
+---
+
+## specifics
+
+None.
+
+## example config
+
+```yaml
+image:
+ - Visual Studio 2019
+
+pull_requests:
+ do_not_increment_build_number: true
+
+skip_branch_with_pr: true
+
+branches:
+ only:
+ - main
+ - develop
+ - /release\/.*/
+ - /hotfix\/.*/
+
+test: off
+build: off
+
+build_script:
+ - ps: .\build.ps1 --target=CI
+
+cache:
+ - "tools -> recipe.cake,tools/packages.config"
+```

docs/input/docs/ci-systems/azure.md

@@ -0,0 +1,40 @@
+---
+Order: 30
+Title: azure pipelines
+Description: Running on azure pipelines
+---
+
+## specifics
+
+None.
+
+## example config
+
+```yaml
+trigger:
+ branches:
+ include:
+ - main
+ - develop
+ - 'release/*'
+ - 'hotfix/*'
+ - 'feature/*'
+ tags:
+ include: [] 
+
+pool:
+ vmImage: 'windows-latest'
+
+steps:
+- task: Cache@2
+ inputs:
+ key: '"$(Agent.OS)" | recipe.cake | .config/dotnet-tools.json'
+ path: 'tools'
+- task: Cake@2
+ inputs:
+ script: 'recipe.cake'
+ target: 'CI'
+ verbosity: 'Diagnostic'
+ Bootstrap: true
+ Version: '0.38.4'
+```

docs/input/docs/ci-systems/github.md

@@ -0,0 +1,79 @@
+---
+Order: 60
+Title: GitHub
+Description: Running on gh-actions
+---
+
+## specifics
+
+* `Upload-Artifacts`-Task
+
+ Uploading artifacts is currently not supported in Cake.Recipe. Please use the actions/upload-artifacts GitHub Action
+
+## example config
+
+```yaml
+name: Build
+
+on:
+ push:
+ branches:
+ - main
+ - develop
+ - "release/**"
+ - "hotfix/**"
+ - "feature/**"
+ tags-ignore:
+ - "*"
+ pull_request:
+
+jobs:
+ build:
+ runs-on: ${{ matrix.os }}
+ strategy:
+ matrix:
+ os: [windows-latest, ubuntu-latest, macos-latest]
+
+ steps:
+ - uses: actions/checkout@v2.2.0
+ with:
+ fetch-depth: 0
+
+ - name: Cache Tools
+ uses: actions/cache@v2
+ with:
+ path: tools
+ key: ${{ runner.os }}-tools-${{ hashFiles('recipe.cake') }}
+
+ - name: Setup .NET Core 2.1
+ uses: actions/setup-dotnet@v1.5.0
+ with:
+ dotnet-version: 2.1.809
+
+ - name: Setup .NET Core 3.1
+ uses: actions/setup-dotnet@v1.5.0
+ with:
+ dotnet-version: 3.1.107
+
+ - name: .net SxS Unix
+ if: matrix.os != 'windows-latest'
+ run: rsync -a ${DOTNET_ROOT/3.1.107/2.1.809}/* $DOTNET_ROOT/
+
+ - name: .net SxS Windows
+ if: matrix.os == 'windows-latest'
+ run: |
+ SET DOTNET_31_ROOT=%DOTNET_ROOT:3.1.107=2.1.809%
+ xcopy /s /y /d %DOTNET_31_ROOT% %DOTNET_ROOT%
+ shell: cmd
+
+ - name: Build project
+ uses: cake-build/cake-action@v1
+ with:
+ script-path: recipe.cake
+ target: CI
+ verbosity: Diagnostic
+ cake-version: 0.38.4
+ cake-bootstrap: true
+
+ # TODO: Upload artifacts...
+```

docs/input/docs/ci-systems/index.cshtml

@@ -0,0 +1,6 @@
+---
+Order: 35
+Description: Overview about CI-systems and how to use them
+---
+
+@Html.Partial("_ChildPages")

docs/input/docs/ci-systems/overview.md

@@ -0,0 +1,21 @@
+---
+Order: 10
+Title: Overview
+Description: On using one or more CI-systems
+---
+
+## Using a CI-System
+
+Generally using Cake.Recipe on any ci-system is not different from using it locally. 
+However, some CI-systems need different preparations than others.
+
+## Using multiple CI-systems (or running multiple builds on the same system)
+
+When a single commit is built multiple times 
+(because of multiple CI-systems and/or multiple builds in the same system)
+some tasks (generelly all tasks that involve some publishing) should only run once (to avoid publishing more than once).
+
+To ensure that those tasks are run only once, Cake.Recipe provides two setting:
+
+* [preferredBuildProviderType](../fundamentals/set-parameters#preferredbuildprovidertype)
+* [preferredBuildAgentOperatingSystem](../fundamentals/set-parameters#preferredbuildprovidertype)

docs/input/docs/ci-systems/teamcity.md

@@ -0,0 +1,7 @@
+---
+Order: 40
+Title: TeamCity
+Description: Running on TeamCity
+---
+
+This documentation is currently missing. 

docs/input/docs/ci-systems/travisci.md

@@ -0,0 +1,7 @@
+---
+Order: 50
+Title: TravisCI
+Description: Running on TravisCI
+---
+
+This documentation is currently missing.