(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,32 @@
+---
+Order: 10
+Title: AppVeyor
+Description: Running on AppVeyor
+---
+
+## Specifics
+
+* PR-Builds
+
+ In organisations with large amounts of projects (like cake-contrib) it is advaisable to *not* run 
+ pull-requests on AppVeyor (if using the OSS-plan in AppVeyor), to
+ reduce the amount of build-time.
+ This change can not be done in the yaml but must be done manually in the UI.
+
+ Go to AppVeyor project -> settings -> "Do not build on "Pull Request" events" to disable building on pull-requests.
+
+## Example Config
+
+```yaml
+image:
+ - Visual Studio 2019
+
+test: off
+build: off
+
+build_script:
+ - ps: .\build.ps1 --target=CI
+
+cache:
+ - "tools -> recipe.cake"
+```

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

@@ -0,0 +1,29 @@
+---
+Order: 20
+Title: Azure Pipelines
+Description: Running on Azure Pipelines
+---
+
+## Specifics
+
+None.
+
+## Example Config
+
+```yaml
+pool:
+ vmImage: 'windows-latest'
+
+steps:
+- task: Cache@2
+ inputs:
+ key: '"$(Agent.OS)" | recipe.cake'
+ path: 'tools'
+- task: Cake@2
+ inputs:
+ script: 'recipe.cake'
+ target: 'CI'
+ verbosity: 'Normal'
+ Bootstrap: true
+ Version: '0.38.4'
+```

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

@@ -0,0 +1,67 @@
+---
+Order: 30
+Title: GitHub Actions
+Description: Building with GitHub Actions
+---
+
+## Specifics
+
+* `Upload-Artifacts`-Task
+
+ Uploading artifacts is currently not supported in Cake.Recipe. Please use the `actions/upload-artifacts` GitHub Action.
+
+* `actions/checkout`
+
+ The default for `fetch-depth` is `1` - this currently does not work with `GitVersion`. Set `fetch-depth: 0` to fetch all history for all branches.
+
+## Example Config
+
+```yaml
+name: Build
+
+on:
+ push:
+
+jobs:
+ build:
+ runs-on: windows-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 3.1
+ uses: actions/setup-dotnet@v1.5.0
+ with:
+ dotnet-version: 3.1.107
+
+ - name: Build project
+ uses: cake-build/cake-action@v1
+ with:
+ script-path: recipe.cake
+ target: CI
+ verbosity: Normal
+ cake-version: 0.38.4
+ cake-bootstrap: true
+
+ - name: Upload Issues-Report
+ uses: actions/upload-artifact@v2
+ with:
+ if-no-files-found: warn
+ name: issues
+ path: BuildArtifacts/report.html
+
+ - name: Upload Packages
+ uses: actions/upload-artifact@v2
+ with:
+ if-no-files-found: warn
+ name: package
+ path: BuildArtifacts/Packages/**/*
+```

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

@@ -0,0 +1,31 @@
+---
+Order: 35
+Title: CI-systems 
+Description: Overview about CI-systems and how to use them
+---
+
+<h2>Using a CI-system</h2>
+<p>
+Generally using Cake.Recipe on any ci-system is not different from using it locally. 
+However, some CI-systems need different preparations than others.
+</p>
+
+
+<h2>Using multiple CI-systems (or running multiple builds on the same system)</h2>
+<p>
+When a single commit is built multiple times 
+(because of multiple CI-systems and/or multiple builds in the same system)
+some tasks (generally all tasks that involve some publishing) should only run once (to avoid publishing more than once).
+</p>
+<p>
+To ensure that those tasks are run only once, Cake.Recipe provides two setting:
+</p>
+
+<ul>
+ <li><a href="../fundamentals/set-parameters#preferredbuildprovidertype">preferredBuildProviderType</a></li>
+ <li><a href="../fundamentals/set-parameters#preferredbuildagentoperatingsystem">preferredBuildAgentOperatingSystem</a></li>
+</ul>
+
+<h2>CI-systems</h2>
+
+@Html.Partial("_ChildPages")

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,42 @@
+---
+Order: 50
+Title: Travis CI
+Description: Running on Travis CI
+---
+
+## Specifics
+
+* `Upload-Artifacts`-Task
+
+ Travis CI does not have artifacts storage therefore uploading artifacts is not supported in Cake.Recipe. 
+
+* `actions/checkout`
+
+ The default for `fetch-depth` currently does not work with `GitVersion`. Set `depth: false` under `git:` to fetch all history for all branches.
+
+## Example Config
+
+*The example shows a build-configuarion for Travis CI, using windows. 
+Keep in mind using windows in Travis CI is currently an [early release](https://docs.travis-ci.com/user/reference/windows)
+and not everything is fully supported.*
+
+```yaml
+language: csharp
+os: windows
+mono: none
+dotnet: none
+
+cache:
+ directories:
+ - tools
+
+git:
+ depth: false
+
+before_install:
+ - choco install dotnetcore-sdk -version 3.1.402
+ - powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine
+
+script:
+ - powershell ./build.ps1
+```