diff --git a/docs/input/docs/recipe/configuration.md b/docs/input/docs/recipe/configuration.md
new file mode 100644
index 00000000..e3df226a
--- /dev/null
+++ b/docs/input/docs/recipe/configuration.md
@@ -0,0 +1,90 @@
+---
+Order: 50
+Title: Configuration
+Description: Available parameters to configure Cake.Issues recipes.
+---
+
+This page lists configuration properties which can be used to define the functionality
+and behavior of Cake.Issues recipes.
+
+# Git repository information
+
+Cake.Issues recipes require some information about current Git repository.
+
+To define the Git provider in `Cake.Issues.Recipe` set the global variable `RepositoryInfoProvider`.
+To define the Git provider in `Cake.Frosting.Issues.Recipe` pass the value to the constructor of `IssueContext`.
+
+The following providers are supported:
+
+| Provider | Description |
+|--------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `RepositoryInfoProviderType.CakeGit` | Read repository information using [Cake.Git addin]. Requires system to be compatible with [Cake.Git addin]. |
+| `RepositoryInfoProviderType.Cli` | Read repository information using Git CLI. Requires Git CLI to be available in path. |
+
+By default [Cake.Git addin] will be used.
+
+# General
+
+| Cake.Issues.Recipe Property | Cake.Frosting.Issues.Recipe Property | Default Value | Description |
+|-------------------------------------------------------------------|---------------------------------------------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `IssuesParameters.`
`OutputDirectory` | `IssuesContext.Parameters.`
`OutputDirectory` | `BuildArtifacts` | Path to the output directory. A relative path will be relative to the current working directory. |
+| `IssuesParameters.`
`BuildIdentifier` | `IssuesContext.Parameters.`
`BuildIdentifier` | `string.Empty` | Identifier for the build run. If set this identifier will be used to identify to artifacts provided by the build if building on multiple configurations. |
+
+# Input files
+
+| Cake.Issues.Recipe Methods | Cake.Frosting.Issues.Recipe Methods | Description |
+|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
+| `IssuesParameters.InputFiles.`
`AddMsBuildXmlFileLoggerLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddMsBuildXmlFileLoggerLogFilePath()` | Adds a path to a MSBuild log file created by XmlFileLogger. |
+| `IssuesParameters.InputFiles.`
`AddMsBuildXmlFileLoggerLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddMsBuildXmlFileLoggerLogFileContent()` | Adds content of a MSBuild log file created by XmlFileLogger. |
+| `IssuesParameters.InputFiles.`
`AddMsBuildBinaryLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddMsBuildBinaryLogFilePath()` | Adds a path to a MSBuild binary log file. |
+| `IssuesParameters.InputFiles.`
`AddMsBuildBinaryLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddMsBuildBinaryLogFileContent()` | Adds content of a MSBuild binary log file. |
+| `IssuesParameters.InputFiles.`
`AddInspectCodeLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddInspectCodeLogFilePath()` | Adds a path to a JetBrains InspectCode log file. |
+| `IssuesParameters.InputFiles.`
`AddInspectCodeLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddInspectCodeLogFileContent()` | Adds content of a JetBrains InspectCode log file. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintCliLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintCliLogFilePath()` | Adds a path to a markdownlint-cli log file. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintCliLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintCliLogFileContent()` | Adds content of a markdownlint-cli log file. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintCliJsonLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintCliJsonLogFilePath()` | Adds a path to a markdownlint-cli log file writting with `--json`. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintCliJsonLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintCliJsonLogFileContent()` | Adds content of a markdownlint-cli log file writting with `--json`. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintV1LogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintV1LogFilePath()` | Adds a path to a markdownlint log file in version 1. |
+| `IssuesParameters.InputFiles.`
`AddMarkdownlintV1LogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddMarkdownlintV1LogFileContent()` | Adds content of a markdownlint log file in version 1. |
+| `IssuesParameters.InputFiles.`
`AddEsLintJsonLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddEsLintJsonLogFilePath()` | Adds a path to a ESLint log file generated by the [ESLint json formatter]. |
+| `IssuesParameters.InputFiles.`
`AddEsLintJsonLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddEsLintJsonLogFileContent()` | Adds content of a ESLint log file generated by the [ESLint json formatter]. |
+| `IssuesParameters.InputFiles.`
`AddSarifLogFilePath()` | `IssuesContext.Parameters.InputFiles.`
`AddSarifLogFilePath()` | Adds a path to a SARIF log file. |
+| `IssuesParameters.InputFiles.`
`AddSarifLogFileContent()` | `IssuesContext.Parameters.InputFiles.`
`AddSarifLogFileContent()` | Adds content of a SARIF log file. |
+
+[ESLint json formatter]: https://eslint.org/docs/user-guide/formatters/#json
+
+# Report creation
+
+| Cake.Issues.Recipe Property | Cake.Frosting.Issues.Recipe Property | Default Value | Description |
+|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
+| `IssuesParameters.Reporting.`
`ShouldCreateFullIssuesReport` | `IssuesContext.Parameters.Reporting.`
`ShouldCreateFullIssuesReport` | `true` | Indicates whether full issues report should be created. |
+| `IssuesParameters.Reporting.`
`FullIssuesReportSettings` | `IssuesContext.Parameters.Reporting.`
`FullIssuesReportSettings` | `GenericIssueReportTemplate.HtmlDxDataGrid` template with `DevExtremeTheme.MaterialBlueLight` theme. | Settings for creating the full issues report. See [Template Gallery] for possible options. |
+| `IssuesParameters.Reporting.`
`ShouldCreateSarifReport` | `IssuesContext.Parameters.Reporting.`
`ShouldCreateSarifReport` | `true` | Indicates whether a report in SARIF format should be created. |
+| `IssuesParameters.Reporting.`
`ShouldReportIssuesToConsole` | `IssuesContext.Parameters.Reporting.`
`ShouldReportIssuesToConsole` | `false` | Indicates whether issues should be reported to the console. |
+| `IssuesParameters.Reporting.`
`ReportToConsoleSettings` | `IssuesContext.Parameters.Reporting.`
`ReportToConsoleSettings` | | Settings for reporting issues to the console. |
+
+[Template Gallery]: /docs/report-formats/generic/templates/
+
+# Build server integration
+
+| Cake.Issues.Recipe Property | Cake.Frosting.Issues.Recipe Property | Default Value | Description |
+|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|---------------|------------------------------------------------------------------------------------------------|
+| `IssuesParameters.BuildServer.`
`ShouldReportIssuesToBuildServer` | `IssuesContext.Parameters.BuildServer.`
`ShouldReportIssuesToBuildServer` | `true` | Indicates whether issues should be reported to the build server. |
+| `IssuesParameters.BuildServer.`
`ShouldPublishFullIssuesReport` | `IssuesContext.Parameters.BuildServer.`
`ShouldPublishFullIssuesReport` | `true` | Indicates whether full issues report should be published as artifact to the build system. |
+| `IssuesParameters.BuildServer.`
`ShouldPublishSarifReport` | `IssuesContext.Parameters.BuildServer.`
`ShouldPublishSarifReport` | `true` | Indicates whether report int SARIF format shoudl be published as artifact to the build system. |
+| `IssuesParameters.BuildServer.`
`ShouldCreateSummaryIssuesReport` | `IssuesContext.Parameters.BuildServer.`
`ShouldCreateSummaryIssuesReport` | `true` | Indicates whether summary issues report should be created. |
+
+# Pull request integration
+
+| Cake.Issues.Recipe Property | Cake.Frosting.Issues.Recipe Property | Default Value | Description |
+|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `IssuesParameters.PullRequestSystem.`
`ShouldReportIssuesToPullRequest` | `IssuesContext.Parameters.PullRequestSystem.`
`ShouldReportIssuesToPullRequest` | `true` | Indicates whether issues should be reported to the pull request system. |
+| `IssuesParameters.PullRequestSystem.`
`MaxIssuesToPost` | `IssuesContext.Parameters.PullRequestSystem.`
`MaxIssuesToPost` | `null` | Global number of issues which should be posted at maximum over all issue provider. Issues are filtered by priority and issues with a file path are prioritized. `null` won't set a global limit. |
+| `IssuesParameters.PullRequestSystem.`
`MaxIssuesToPostAcrossRuns` | `IssuesContext.Parameters.PullRequestSystem.`
`MaxIssuesToPostAcrossRuns` | `null` | Global number of issues which should be posted at maximum over all issue providers and across multiple runs. Issues are filtered by priority and issues with a file path are prioritized. `null` won't set a limit across multiple runs. |
+| `IssuesParameters.PullRequestSystem.`
`MaxIssuesToPostForEachIssueProvider` | `IssuesContext.Parameters.PullRequestSystem.`
`MaxIssuesToPostForEachIssueProvider` | `100` | Number of issues which should be posted at maximum for each issue provider. Issues are filtered by priority and issues with a file path are prioritized. `null` won't limit issues per issue provider. |
+| `IssuesParameters.PullRequestSystem.`
`ProviderIssueLimits` | `IssuesContext.Parameters.PullRequestSystem.`
`ProviderIssueLimits` | Empty | Issue limits for individual issue provider. The key must be the `IIssue.ProviderType` of a specific provider to which the limits should be applied to. |
+| `IssuesParameters.PullRequestSystem.`
`IssueFilters` | `IssuesContext.Parameters.PullRequestSystem.`
`IssueFilters` | Empty | List of filter functions which should be applied before posting issues to pull requests. |
+| `IssuesParameters.PullRequestSystem.`
`ShouldSetPullRequestStatus` | `IssuesContext.Parameters.PullRequestSystem.`
`ShouldSetPullRequestStatus` | `true` | Indicates whether a status on the pull request should be set if there are any issues found. |
+| `IssuesParameters.PullRequestSystem.`
`ShouldSetSeparatePullRequestStatusForEachIssueProviderAndRun` | `IssuesContext.Parameters.PullRequestSystem.`
`ShouldSetSeparatePullRequestStatusForEachIssueProviderAndRun` | `true` | Indicates whether a separate status should be set for issues of every issue provider and run. |
+
+[Cake.Git addin]: https://cakebuild.net/extensions/cake-git/
diff --git a/docs/input/docs/recipe/demos.md b/docs/input/docs/recipe/demos.md
new file mode 100644
index 00000000..b8cca3e9
--- /dev/null
+++ b/docs/input/docs/recipe/demos.md
@@ -0,0 +1,12 @@
+---
+Order: 40
+Title: Demos
+Description: Demo setups for Cake.Issues recipes.
+---
+
+There are demo setups available for different combinations of build servers and repositories which you can fork and to which you can create pull requests
+to test the recipe functionality.
+
+| Recipe | Build Server | Repository |
+|--------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| Cake.Issues.Recipe | [Azure Pipelines](https://dev.azure.com/pberger/Cake.Issues.Recipe-Demo/_build/latest?definitionId=6) | [Azure Repos](https://dev.azure.com/pberger/_git/Cake.Issues.Recipe-Demo) |
\ No newline at end of file
diff --git a/docs/input/docs/recipe/index.cshtml b/docs/input/docs/recipe/index.cshtml
new file mode 100644
index 00000000..79cf416e
--- /dev/null
+++ b/docs/input/docs/recipe/index.cshtml
@@ -0,0 +1,7 @@
+---
+Order: 40
+Description: Using Cake.Issues addins with a pre-made recipe script.
+---
+
@Html.Raw(Model.String(DocsKeys.Description))
+ +@Html.Partial("_ChildPages") \ No newline at end of file diff --git a/docs/input/docs/recipe/overview.md b/docs/input/docs/recipe/overview.md new file mode 100644 index 00000000..b7b44b21 --- /dev/null +++ b/docs/input/docs/recipe/overview.md @@ -0,0 +1,78 @@ +--- +Order: 10 +Title: Overview +Description: Overview about Cake.Issues recipes. +--- +Cake.Issues recipes provide build scripts, delivered as a NuGet package, which can be used inside your projects Cake build to add issue management. + +Integration of code analyzing and linting tools into a build pipeline often looks the similar, and differentiates mainly on the used linters, build and pull request systems. +Cake.Issues recipes contain code to do all the parsing, integration with build and pull request systems for you, using the individual Cake.Issues addins. +They support different linters based on the linting log files you pass it and integrate automatically with different build and pull request systems. + +There are two flavors available: + +* [Cake.Issues.Recipe]: For [Cake .NET Tool], [Cake runner for .NET Framework] or [Cake runner for .NET Core] +* [Cake.Frosting.Issues.Recipe]: For [Cake Frosting] + +# Supported tools + +See [supported tools] for a list of supported linters, build servers and pull request systems. + +# Bundled addins + +Cake.Issues recipes will add the following addins to your build: + +| Addin Cake.Issues.Recipe | Addin.Frosting.Issues.Recipe | Remarks | +|---------------------------------------------------------|------------------------------------------------------------------|-| +| [Cake.Git] 5.0.1 | [Cake.Frosting.Git] 5.0.1 | Only used if `RepositoryInfoProvider` type is set to `RepositoryInfoProviderType.CakeGit`. See [Git repository information configuration] for details. | +| [Cake.Issues] 5.0.1 | [Cake.Issues] 5.0.1 | | +| [Cake.Issues.MsBuild] 5.0.1 | [Cake.Frosting.Issues.MsBuild] 5.0.1 | | +| [Cake.Issues.InspectCode] 5.0.1 | [Cake.Frosting.Issues.InspectCode] 5.0.1 | | +| [Cake.Issues.Markdownlint] 5.0.1 | [Cake.Frosting.Issues.Markdownlint] 5.0.1 | | +| [Cake.Issues.EsLint] 5.0.1 | [Cake.Frosting.Issues.EsLint] 5.0.1 | | +| [Cake.Issues.Sarif] 5.0.1 | [Cake.Frosting.Issues.Sarif] 5.0.1 | | +| [Cake.Issues.Reporting] 5.0.1 | [Cake.Frosting.Issues.Reporting] 5.0.1 | | +| [Cake.Issues.Reporting.Generic] 5.0.1 | [Cake.Frosting.Issues.Reporting.Generic] 5.0.1 | | +| [Cake.Issues.Reporting.Sarif] 5.0.1 | [Cake.Frosting.Issues.Reporting.Sarif] 5.0.1 | | +| [Cake.Issues.PullRequests] 5.0.1 | [Cake.Frosting.Issues.PullRequests] 5.0.1 | | +| [Cake.Issues.PullRequests.AppVeyor] 5.0.1 | [Cake.Frosting.Issues.PullRequests.AppVeyor] 5.0.1 | | +| [Cake.Issues.PullRequests.AzureDevOps] 5.0.1 | [Cake.Frosting.Issues.PullRequests.AzureDevOps] 5.0.1 | | +| [Cake.Issues.PullRequests.GitHubActions] 5.0.1 | [Cake.Frosting.Issues.PullRequests.GitHubActions] 5.0.1 | | +| [Cake.AzureDevOps] 5.0.0 | [Cake.AzureDevOps] 5.0.0 | | + +[Cake.Issues.Recipe]: https://www.nuget.org/packages/Cake.Issues.Recipe +[Cake.Frosting.Issues.Recipe]: https://www.nuget.org/packages/Cake.Frosting.Issues.Recipe +[Cake .NET Tool]: https://cakebuild.net/docs/running-builds/runners/dotnet-tool +[Cake runner for .NET Framework]: https://cakebuild.net/docs/running-builds/runners/cake-runner-for-dotnet-framework +[Cake runner for .NET Core]: https://cakebuild.net/docs/running-builds/runners/cake-runner-for-dotnet-core +[Cake Frosting]: https://cakebuild.net/docs/running-builds/runners/cake-frosting +[supported tools]: supported-tools +[Git repository information configuration]: /docs/recipe/configuration#git-repository-information +[Cake.Git]: https://cakebuild.net/extensions/cake-git/ +[Cake.Frosting.Git]: https://cakebuild.net/extensions/cake-git/ +[Cake.Issues]: https://cakebuild.net/extensions/cake-issues/ +[Cake.Issues.MsBuild]: https://cakebuild.net/extensions/cake-issues-msbuild/ +[Cake.Frosting.Issues.MsBuild]: https://cakebuild.net/extensions/cake-issues-msbuild/ +[Cake.Issues.InspectCode]: https://cakebuild.net/extensions/cake-issues-inspectcode/ +[Cake.Frosting.Issues.InspectCode]: https://cakebuild.net/extensions/cake-issues-inspectcode/ +[Cake.Issues.Markdownlint]: https://cakebuild.net/extensions/cake-issues-markdownlint/ +[Cake.Frosting.Issues.Markdownlint]: https://cakebuild.net/extensions/cake-issues-markdownlint/ +[Cake.Issues.EsLint]: https://cakebuild.net/extensions/cake-issues-eslint/ +[Cake.Frosting.Issues.EsLint]: https://cakebuild.net/extensions/cake-issues-eslint/ +[Cake.Issues.Sarif]: https://cakebuild.net/extensions/cake-issues-sarif/ +[Cake.Frosting.Issues.Sarif]: https://cakebuild.net/extensions/cake-issues-sarif/ +[Cake.Issues.Reporting]: https://cakebuild.net/extensions/cake-issues-reporting/ +[Cake.Frosting.Issues.Reporting]: https://cakebuild.net/extensions/cake-issues-reporting/ +[Cake.Issues.Reporting.Generic]: https://cakebuild.net/extensions/cake-issues-reporting-generic/ +[Cake.Frosting.Issues.Reporting.Generic]: https://cakebuild.net/extensions/cake-issues-reporting-generic/ +[Cake.Issues.Reporting.Sarif]: https://cakebuild.net/extensions/cake-issues-reporting-sarif/ +[Cake.Frosting.Issues.Reporting.Sarif]: https://cakebuild.net/extensions/cake-issues-reporting-sarif/ +[Cake.Issues.PullRequests]: https://cakebuild.net/extensions/cake-issues-pullrequests/ +[Cake.Frosting.Issues.PullRequests]: https://cakebuild.net/extensions/cake-issues-pullrequests/ +[Cake.Issues.PullRequests.AppVeyor]: https://cakebuild.net/extensions/cake-issues-pullrequests-appveyor/ +[Cake.Frosting.Issues.PullRequests.AppVeyor]: https://cakebuild.net/extensions/cake-issues-pullrequests-appveyor/ +[Cake.Issues.PullRequests.AzureDevOps]: https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/ +[Cake.Frosting.Issues.PullRequests.AzureDevOps]: https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/ +[Cake.Issues.PullRequests.GitHubActions]: https://cakebuild.net/extensions/cake-issues-pullrequests-githubactions/ +[Cake.Frosting.Issues.PullRequests.GitHubActions]: https://cakebuild.net/extensions/cake-issues-pullrequests-githubactions/ +[Cake.AzureDevOps]: https://cakebuild.net/extensions/cake-azuredevops/ diff --git a/docs/input/docs/recipe/supported-tools.md b/docs/input/docs/recipe/supported-tools.md new file mode 100644 index 00000000..e6280580 --- /dev/null +++ b/docs/input/docs/recipe/supported-tools.md @@ -0,0 +1,48 @@ +--- +Order: 30 +Title: Supported tools +Description: Tools supported by Cake.Issues recipes. +--- + +Cake.Issues recipes support reading issues from different tools and integrates with different build and pull request systems. + +# Tools + +Cake.Issues recipes support reading issues from output of the following tools: + +| Tool | Format | Cake.Issues.Recipe Methods | Cake.Frosting.Issues.Recipe Method | +|-----------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| MsBuild | [MSBuild Extension Pack XmlFileLogger] | `IssuesParameters.InputFiles.`@Html.Raw(Model.String(DocsKeys.Description))
+ +@Html.Partial("_ChildPages") \ No newline at end of file diff --git a/docs/input/docs/recipe/usage/using-cake-frosting-issues-recipe.md b/docs/input/docs/recipe/usage/using-cake-frosting-issues-recipe.md new file mode 100644 index 00000000..7a371552 --- /dev/null +++ b/docs/input/docs/recipe/usage/using-cake-frosting-issues-recipe.md @@ -0,0 +1,126 @@ +--- +Order: 20 +Title: Using Cake.Frosting.Issues.Recipe +Description: Basic usage of Cake.Frosting.Issues.Recipe. +--- +The [Cake.Frosting.Issues.Recipe] package can be used to easily add issue management functionality to your Cake Frosting build. + +:::{.alert .alert-info} +See [Setting Up A New Frosting Project] for instructions how to create a new Cake Frosting project. +::: + +[Setting Up A New Frosting Project]: https://cakebuild.net/docs/getting-started/setting-up-a-new-frosting-project + +# Add Cake.Frosting.Issues.Recipe to your Cake Frosting build + +To use [Cake.Frosting.Issues.Recipe] in your Cake Frosting build you need to first add the NuGet package in your `.csproj` file: + +```csharp +