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.`
    `AddMsBuildXmlFileLoggerLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddMsBuildXmlFileLoggerLogFile*()` | +| MsBuild | Binary Log File | `IssuesParameters.InputFiles.`
    `AddMsBuildBinaryLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddMsBuildBinaryLogFile*()` | +| JetBrains InspectCode (ReSharper) | | `IssuesParameters.InputFiles.`
    `AddInspectCodeLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddInspectCodeLogFile*()` | +| markdownlint | [markdownlint-cli] | `IssuesParameters.InputFiles.`
    `AddMarkdownlintCliLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddMarkdownlintCliLogFile*()` | +| markdownlint | [markdownlint-cli] with `--json` | `IssuesParameters.InputFiles.`
    `AddMarkdownlintCliJsonLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddMarkdownlintCliJsonLogFile*()` | +| markdownlint | [markdownlint] version 1 | `IssuesParameters.InputFiles.`
    `AddMarkdownlintV1LogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddMarkdownlintV1LogFile*()` | +| [ESLint] | [json formatter] | `IssuesParameters.InputFiles.`
    `AddEsLintJsonLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddEsLintJsonLogFile*()` | +| Any SARIF compatible tool | [SARIF] | `IssuesParameters.InputFiles.`
    `AddSarifLogFile*()` | `IssuesContext.Parameters.InputFiles.`
    `AddSarifLogFile*()` | + +[MSBuild Extension Pack XmlFileLogger]: http://www.msbuildextensionpack.com/help/4.0.5.0/html/242ab4fd-c2e2-f6aa-325b-7588725aed24.htm +[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli +[markdownlint]: https://github.com/DavidAnson/markdownlint +[ESLint]: https://eslint.org/ +[json formatter]: https://eslint.org/docs/user-guide/formatters/#json +[SARIF]: https://sarifweb.azurewebsites.net/ + +# Build systems + +Cake.Issues recipes integrates with the following build systems: + +| Build System | Write issues to build server | Issues summary | Full issues report | +|--------------------------------|-----------------------------------------------------------------------------------|--------------------------------------------------------------------|--------------------------------------------------------------------| +| AppVeyor | | | | +| Azure Pipelines (Azure DevOps) | (Only first 10) | | | +| GitHub Actions | | | | + +# Pull request systems + +Cake.Issues recipes integrates with the following pull request systems: + +| Pull Request System | Write issues to pull requests | Set pull request status | +|----------------------------|----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| +| Azure Repos (Azure DevOps) | | | +| GitHub | (When build from GitHub Actions) | | diff --git a/docs/input/docs/recipe/tasks.md b/docs/input/docs/recipe/tasks.md new file mode 100644 index 00000000..1af33410 --- /dev/null +++ b/docs/input/docs/recipe/tasks.md @@ -0,0 +1,19 @@ +--- +Order: 60 +Title: Tasks +Description: Tasks provided by Cake.Issues recipes. +--- + +Cake.Issues recipes provide the following tasks to your build script: + +| Task | Description | Cake.Issues.Recipe task instance | Cake.Frosting.Issues.Recipe task type | +|------------------------------|----------------------------------------------|---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| +| `Issues` | Main tasks for issue management integration. | `IssuesBuildTasks.`
    `IssuesTask` | `Cake.Frosting.Issues.Recipe.`
    `IssuesTask` | +| `Read-Issues` | Reads issues from the provided log files. | `IssuesBuildTasks.`
    `ReadIssuesTask` | `Cake.Frosting.Issues.Recipe.`
    `ReadIssuesTask` | +| `Create-FullIssuesReport` | Creates issue report. | `IssuesBuildTasks.`
    `CreateFullIssuesReportTask` | `Cake.Frosting.Issues.Recipe.`
    `CreateFullIssuesReportTask` | +| `Publish-IssuesArtifacts` | Publish artifacts to build server. | `IssuesBuildTasks.`
    `PublishIssuesArtifactsTask` | `Cake.Frosting.Issues.Recipe.`
    `PublishIssuesArtifactsTask` | +| `Report-IssuesToBuildServer` | Report issues to build server. | `IssuesBuildTasks.`
    `ReportIssuesToBuildServerTask` | `Cake.Frosting.Issues.Recipe.`
    `ReportIssuesToBuildServerTask` | +| `Create-SummaryIssuesReport` | Creates a summary issue report. | `IssuesBuildTasks.`
    `CreateSummaryIssuesReportTask` | `Cake.Frosting.Issues.Recipe.`
    `CreateSummaryIssuesReportTask` | +| `Report-IssuesToPullRequest` | Report issues to pull request. | `IssuesBuildTasks.`
    `ReportIssuesToPullRequestTask` | `Cake.Frosting.Issues.Recipe.`
    `ReportIssuesToPullRequestTask` | +| `Set-PullRequestIssuesState` | Set pull request status. | `IssuesBuildTasks.`
    `SetPullRequestIssuesStateTask` | `Cake.Frosting.Issues.Recipe.`
    `SetPullRequestIssuesStateTask` | +| `Report-IssuesToConsole` | Report issues to console. | `IssuesBuildTasks.`
    `ReportIssuesToConsoleTask` | `Cake.Frosting.Issues.Recipe.`
    `ReportIssuesToConsoleTask` | \ No newline at end of file diff --git a/docs/input/docs/recipe/usage/index.cshtml b/docs/input/docs/recipe/usage/index.cshtml new file mode 100644 index 00000000..190abe4f --- /dev/null +++ b/docs/input/docs/recipe/usage/index.cshtml @@ -0,0 +1,7 @@ +--- +Order: 20 +Description: How to use Cake.Issues recipes in your build script. +--- +

@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 + +``` + +:::{.alert .alert-warning} +Replace the version (`1.0.0`) with the version of Cake.Frosting.Issues.Recipe you want to use. +::: + +# Register Cake.Issues tasks + +To make Cake Issues tasks available to your Cake Frosting build you need to register them. + +Add the following line to the bootstrapping code in the `Main` method of your Cake Frosting project: + +```csharp +AddAssembly(Assembly.GetAssembly(typeof(IssuesTask))) +``` + +The following bootstrapping code registers the Cake Issues tasks and also installs JetBrains InspectCode: + +```csharp +using System; +using System.Reflection; +using Cake.Frosting; +using Cake.Frosting.Issues.Recipe; + +public static class Program +{ + public static int Main(string[] args) + { + return new CakeHost() + .UseContext() + .InstallTool(new Uri("nuget:?package=JetBrains.ReSharper.CommandLineTools")) + .AddAssembly(Assembly.GetAssembly(typeof(IssuesTask))) + .Run(args); + } +} +``` + +# Create build context + +[Cake.Frosting.Issues.Recipe] provides a build context from which you need to inherit your custom build context. +The build context contains configuration parameters, but also the state of the current running build, +like for example all collected issues. + +The following example creates a build context and defines that Cake Issues should use Cake.Git addin to determine +state of the Git repository: + +```csharp +public class BuildContext : IssuesContext +{ + public BuildContext(ICakeContext context) + : base(context, RepositoryInfoProviderType.CakeGit) + { + } +} +``` + +# Passing issues to Cake.Frosting.Issues.Recipe + +To make issues available to [Cake.Frosting.Issues.Recipe] you need pass the log files through the corresponding methods. +The tasks need to also be a dependency of `ReadIssuesTask` provided by [Cake.Frosting.Issues.Recipe]. + +In the following example a new task is introduced which runs JetBrains InspectCode and passes the log file to [Cake.Frosting.Issues.Recipe]: + +```csharp +[TaskName("Run-InspectCode")] +[IsDependeeOf(typeof(ReadIssuesTask))] +public class RunInspectCodeTask : FrostingTask +{ + public override void Run(BuildContext context) + { + var inspectCodeLogFilePath = context.Parameters.OutputDirectory..CombineWithFilePath("inspectCode.log"); + + // Run JetBrains InspectCode + context.InspectCode( + context.State.RepositoryRootDirectory.Combine("src").CombineWithFilePath("ClassLibrary1.sln"), + new InspectCodeSettings() { + OutputFile = context.InspectCodeLogFilePath + }); + + // Pass path to InspectCode log file to Cake.Frosting.Issues.Recipe + context.Parameters.InputFiles.AddInspectCodeLogFilePath(context.InspectCodeLogFilePath); + } +} +``` + +See [configuration] for a full list of available configuration parameters. + +# Calling issues tasks + +[Cake.Frosting.Issues.Recipe] will add a bunch of [tasks] to your build script. + +To add the issues functionality into your existing build pipeline you need to add +`ReadIssuesTask` to your pipeline. + + In the following example the `Default` task makes sure the main `IssuesTask` is executed: + +```csharp +[TaskName("Default")] +[IsDependentOn(typeof(IssuesTask))] +public class DefaultTask : FrostingTask +{ +} +``` + +[Cake.Frosting.Issues.Recipe]: ../../recipe/ +[configuration]: ../../recipe/configuration +[tasks]: ../../recipe/tasks \ No newline at end of file diff --git a/docs/input/docs/recipe/usage/using-cake-issues-recipe.md b/docs/input/docs/recipe/usage/using-cake-issues-recipe.md new file mode 100644 index 00000000..71cbc419 --- /dev/null +++ b/docs/input/docs/recipe/usage/using-cake-issues-recipe.md @@ -0,0 +1,68 @@ +--- +Order: 10 +Title: Using Cake.Issues.Recipe +Description: Basic usage of Cake.Issues.Recipe. +--- +The [Cake.Issues.Recipe] package can be used to easily add issue management functionality to your build script. + +# Add Cake.Issues.Recipe to your build script + +To use Cake.Issues.Recipe in your build script you need to first load the NuGet package: + +```csharp +#load nuget:package=Cake.Issues.Recipe +``` + +:::{.alert .alert-warning} +Please note that you always should pin NuGet packages to a specific version to make sure your builds are deterministic and +won't break due to updates to Cake.Issues.Recipe. + +See [pinning addin versions](https://cakebuild.net/docs/tutorials/pinning-cake-version#pinning-addin-version) for details. +::: + +# Configuring Cake.Issues.Recipe + +To make issues available to Cake.Issues.Recipe you need to set the corresponding configuration parameters. + +In the following example a new task is introduced which depends on existing tasks which build a MsBuild solution and run JetBrains InspectCode. +It will pass the MsBuild and InspectCode logfile to Cake.Issues.Recipe: + +```csharp +// Run issues task by default. +Task("Configure-CakeIssuesRecipe") + .IsDependentOn("Build") + .IsDependentOn("Run-InspectCode") + .Does(() => +{ + IssuesParameters.InputFiles.AddMsBuildXmlFileLoggerLogFilePath(msBuildLogFilePath); + IssuesParameters.InputFiles.AddInspectCodeLogFilePath(inspectCodeLogFilePath); +} +``` + +See [configuration] for a full list of available configuration parameters. + +# Calling issues tasks + +Cake.Issues.Recipe will add a bunch of [tasks] to your build script. + +To add the issues functionality into your existing build pipeline you can make +the `Read-Issues` task dependent on the task which configures Cake.Issues.Recipe: + +```csharp +// Make sure build and linters run before issues task. +IssuesBuildTasks.ReadIssuesTask + .IsDependentOn("Configure-CakeIssuesRecipe"); +``` + +At some point you need to call the tasks provided by Cake.Isses.Recipe. +In the following example the `Default` task calls the main `Issues` task: + +```csharp +// Run issues task by default. +Task("Default") + .IsDependentOn("Issues"); +``` + +[Cake.Issues.Recipe]: ../../recipe/ +[configuration]: ../../recipe/configuration +[tasks]: ../../recipe/tasks \ No newline at end of file