diff --git a/docs/docs/documentation/fundamentals/overview.png b/docs/docs/documentation/assets/images/overview.png similarity index 100% rename from docs/docs/documentation/fundamentals/overview.png rename to docs/docs/documentation/assets/images/overview.png diff --git a/docs/docs/documentation/features.md b/docs/docs/documentation/features.md new file mode 100644 index 000000000..5b80fdedd --- /dev/null +++ b/docs/docs/documentation/features.md @@ -0,0 +1,161 @@ +--- +title: Features +description: Overview about core features. +--- + +## Ready To Use Distributions + +
+ +- :material-arrow-collapse-all:{ .lg .middle } __Cake Recipe Packages__ + + --- + + Cake Issues recipes provide build scripts, delivered as a NuGet package, + which can be used inside your projects Cake build to add issue management. + + It handles all the parsing, integration with build and pull request systems for you, + using the individual Cake Issues addins. + + [:octicons-arrow-right-24: Recipes](recipe/overview.md) + +
+ +## Reading & Creating Issues + +
+ +- :material-import:{ .lg .middle } __Read issues provided by tools__ + + --- + + The `ReadIssues` aliases can be used for reading issues reported by a linter to tool using an [issue provider]. + + There are overloads for reading using a single or multiple [issue provider]. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Reading-Issues){target="_blank"} + +- :material-creation-outline:{ .lg .middle } __Create issues in your build__ + + --- + + The `NewIssue` aliases can be used for creating issues in the build script. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Creating-Issues){target="_blank"} + +- :material-file-link:{ .lg .middle } __Support for file links__ + + --- + + Support for creating links to file & location on source code hosting system (GitHub, Azure Repos, etc). + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#File-Linking){target="_blank"} + +- :material-swap-vertical-bold:{ .lg .middle } __Issue serialization__ + + --- + + Support for serializing and deserializing created issues and issues read from tools. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Issue-Serialization){target="_blank"} + +- :material-format-title:{ .lg .middle } __Support for multiple message formats__ + + --- + + Support for reading issues in multiple formats (Plain text, Markdown, HTML) if supported by [issue provider]. + +- :material-information:{ .lg .middle } __Support for run information__ + + --- + + Support for passing additional run information to identify specific runs. + +
+ +## Breaking builds + +
+ +- :material-exclamation:{ .lg .middle } __Fail builds on reported issues__ + + --- + + The `BreakBuildOnIssues` aliases can be used for failing builds if specific issues were reported. + + There are overloads for failing if issues of certain minimum priority or issue providers are found, + or by passing any custom function. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Build-Breaking){target="_blank"} + +
+ +## Reporting + +
+ +- :material-monitor-dashboard:{ .lg .middle } __Create reports__ + + --- + + The `CreateIssueReport` aliases can be used for creating reports in a supported [reporting format]. + + There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-reporting/#Creating-Issue-Reports){target="_blank"} + +
+ +## Build & Pull Request System Integration + +
+ +- :material-comment-text:{ .lg .middle } __Add comments to pull requests__ + + --- + + The `ReportIssuesToPullRequest` aliases can be used for writing issues as comments to [pull requests]. + + There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-pullrequests/#Reporting-Issues-To-Pull-Requests){target="_blank"} + +- :material-message-plus:{ .lg .middle } __Report issues to build runs__ + + --- + + The `ReportIssuesToPullRequest` aliases can be used for reporting issues to [build runs]. + + There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues. + + [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-pullrequests/#Reporting-Issues-To-Pull-Requests){target="_blank"} + +- :material-filter:{ .lg .middle } __Issue filters__ + + --- + + Support for passing custom issue filter routines. + + [:octicons-arrow-right-24: Setting](https://cakebuild.net/api/Cake.Issues.PullRequests/IReportIssuesToPullRequestSettings/48CB35E4){target="_blank"} + +- :material-car-speed-limiter:{ .lg .middle } __Limit reported issues__ + + --- + + Advanced support to limit number of maximum issues per run, across multiple runs or per issue provider through settings. + + [:octicons-arrow-right-24: Settings](https://cakebuild.net/api/Cake.Issues.PullRequests/IReportIssuesToPullRequestSettings/){target="_blank"} + +- :material-comment-check:{ .lg .middle } __Automatic comment resolving__ + + --- + + If supported by the [pull request system], comments for issues are automatic resolved if fixed in subsequent commits. + +
+ +[issue provider]: issue-providers/index.md +[reporting format]: report-formats/index.md +[pull requests]: pull-request-systems/index.md +[build runs]: pull-request-systems/index.md +[pull request system]: pull-request-systems/index.md diff --git a/docs/docs/documentation/fundamentals/architecture.md b/docs/docs/documentation/fundamentals/architecture.md deleted file mode 100644 index e1decb60e..000000000 --- a/docs/docs/documentation/fundamentals/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Architecture -description: Architecture overview. ---- - -The Cake Issues addins are built in a modular architecture, allowing to easily -enhance it for supporting additional analyzers, linters, report formats and pull request systems. - -![Architecture Overview](overview.png "Architecture Overview") - -The core consists of the following addins: - -| Addin | Description | -|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Cake.Issues | Provides aliases for creating issues or reading issues using one or more issue providers. Support for different code analyzers and linters can be provided through additional [issue provider] addins. | -| Cake.Issues.Reporting | Provides aliases for creating reports for issues. Support for different report formats can be provided through additional [report format] addins. | -| Cake.Issues.PullRequests | Provides aliases for reporting issues as comments to pull requests. Support for different pull request systems can be provided through additional [pull request system] addins. | - -[issue provider]: ../issue-providers/index.md -[report format]: ../report-formats/index.md -[pull request system]: ../pull-request-systems/index.md diff --git a/docs/docs/documentation/fundamentals/versioning.md b/docs/docs/documentation/fundamentals/versioning.md deleted file mode 100644 index 0e119588f..000000000 --- a/docs/docs/documentation/fundamentals/versioning.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Versioning -description: Compatible versions. ---- - -The core addins and all issue providers and pull request systems need to be build against a compatible core API. -You can check the required dependencies in the release notes of the addin. - -This means that it's not possible to use a version of an issue provider build against `Cake.Issues` 1.0.0 -together with a version of a pull request system build against `Cake.Issues` 2.0.0. - -We use strict [semantic versioning](http://semver.org/){target="_blank"}. -Therefore it's possible to use issue provider and pull request system built against `Cake.Issues` 1.0.0 -together with `Cake.Issues` 1.1.0. - -!!! info - Please note that versions below 1.0.0 are not considered stable and their API will break regularly. - Expect breaking changes in each minor version. - - Therefore we strongly advise to pin to specific versions of the addins to avoid breaking builds - once we update the addin. diff --git a/docs/docs/documentation/how-cake-issues-works.md b/docs/docs/documentation/how-cake-issues-works.md new file mode 100644 index 000000000..b9b8db2df --- /dev/null +++ b/docs/docs/documentation/how-cake-issues-works.md @@ -0,0 +1,45 @@ +--- +title: How Cake Issues Works +description: Overview about the architecture of Cake Issues. +--- + +The Cake Issues addins are built in a modular architecture, allowing to easily +enhance it for supporting additional analyzers, linters, report formats and pull request systems. + +![Architecture Overview](assets/images/overview.png "Architecture Overview") + +## Cake.Issues addin + +The `Cake.Issues` addin provides aliases for creating issues or reading issues using one or more issue providers. + +Support for different code analyzers and linters is provided through [issue provider] addins +which cover a wide range of [linters and tools]. + +The issues are read into [IIssue](https://cakebuild.net/api/Cake.Issues/IIssue/){target="_blank"} objects +which then can be passed to [Cake.Issues.Reporting addin](#cakeissuesreporting-addin), +[Cake.Issues.PullRequests addin](#cakeissuespullrequests-addin) or further processed in the build script. + +The use of [issue provider] addins, which contain the parsing logic for individual tool output formats, +and the use of [IIssue](https://cakebuild.net/api/Cake.Issues/IIssue/){target="_blank"} as common data structure, +allows to abstract the tooling output from other concerns like integration with +build systems, pull request workflow or the creation of reports. + +## Cake.Issues.Reporting addin + +The `Cake.Issues.Reporting` addin provides aliases for creating reports for issues +which are read or have been created using the [Cake.Issues addin](#cakeissues-addin). + +Support for different report formats is provided through [report format] addins. + +## Cake.Issues.PullRequests addin + +The `Cake.Issues.PullRequests` addin provides aliases for reporting issues +which are read or have been created using the [Cake.Issues addin](#cakeissues-addin) +as comments to pull requests or builds. + +Support for different pull request systems is provided through [pull request system] addins. + +[issue provider]: issue-providers/index.md +[linters and tools]: supported-tools.md +[report format]: report-formats/index.md +[pull request system]: pull-request-systems/index.md diff --git a/docs/docs/documentation/overview.md b/docs/docs/documentation/overview.md new file mode 100644 index 000000000..0f91c525b --- /dev/null +++ b/docs/docs/documentation/overview.md @@ -0,0 +1,106 @@ +--- +title: Introduction +description: Introduction +--- + +The Cake.Issues addins for the [Cake build automation system](https://cakebuild.net){target="_blank"} +offer an extensive and flexible solution for reading linting issues. + +Cake.Issues redefines issue management within the Cake build system by offering a comprehensive, universal, and extensible solution. +The unique capabilities of the addins empower development teams to enforce coding standards, generate insightful reports, +seamlessly incorporate various linting tools, and streamlining the integration with pull requests. +With its [modular architecture] and extensive [set of aliases](https://cakebuild.net/extensions/cake-issues/){target="_blank"}, +Cake.Issues provides a future-proof infrastructure for issue management in Cake builds, +fostering a more efficient and adaptable development process. + +## Unique Problem Solving + +Some examples how Cake.Issues can help development teams to improve code quality. + +### Break build on linting issues + +Cake.Issues provides a seamless integration, allowing you to enforce coding standards by breaking builds when linting issues are detected. + +[:octicons-arrow-right-24: Aliases for build breaking](https://cakebuild.net/extensions/cake-issues/#Build-Breaking){target="_blank"} + +### Pull Requests integration + +Ensure linting issues are promptly addressed by having them reported as comments on pull requests. +Cake.Issues bridges the gap between linting tools and version control systems, fostering efficient collaboration during code reviews. + +[:octicons-arrow-right-24: Integrate with pull request systems](pull-request-systems/index.md) + +### Reports + +Craft detailed and visually appealing reports for linting issues directly within your Cake build. +The addins facilitates easy identification and resolution of linting concerns, enhancing the overall code quality. + +[:octicons-arrow-right-24: Creating Reports](report-formats/index.md) + +## Universal Compatibility + +### Diverse Linting Tool Support + +Regardless of the linting tools you use, Cake.Issues ensures that you're not left out. +Cake.Issues supports a variety of analyzers and linters, allowing you to incorporate new tools effortlessly +while maintaining integration with existing ones. + +[:octicons-arrow-right-24: Supported Tools](supported-tools.md) + +### Build System Agnosticism + +Embrace the freedom to choose the build system that best suit your needs. +If your current build system lacks tasks for reporting issues in pull requests, Cake.Issues steps in to fill that void seamlessly. +In the case of using multiple CI services, Cake.Issues guarantees a consistent feature set across all of them. + +[:octicons-arrow-right-24: Supported Build and pull request systems](pull-request-systems/index.md) + +## Unprecedented Extensibility + +### Modular Architecture + +The Cake.Issues addin breaks away from the norm by offering a modular architecture. +Comprising over 15 distinct addins, it presents a cohesive solution through more than 75 aliases for Cake builds, +providing unparalleled flexibility. + +[:octicons-arrow-right-24: Architecture](how-cake-issues-works.md) + +### Extensible Infrastructure + +Designed with extensibility in mind, Cake.Issues provides extension points for supporting additional +analyzers, linters,report formats, and code review systems. +This adaptability ensures that your build scripts can evolve with the ever-changing landscape of development tools. + +[:octicons-arrow-right-24: Documentation](extending/index.md) + + + +[modular architecture]: how-cake-issues-works.md + diff --git a/docs/docs/documentation/overview/features.md b/docs/docs/documentation/overview/features.md deleted file mode 100644 index f7c82a6c5..000000000 --- a/docs/docs/documentation/overview/features.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Features -description: Overview about core features. ---- - -The Cake Issues addins for Cake allows you to read issues from any analyzer or linter, -create reports or write issues to comments in pull requests. - -## Recipe Functionality - -See [Supported Tools] for a list of tools supported by [Cake.Issues.Recipe]. - -## Supported Core Functionality - -The core addins provide a modular architecture, allowing to easily enhance it for supporting additional analyzers, linters, -report formats and code review systems. - -### Cake.Issues - -Addin for creating and reading issues providing the following functionality: - -* [NewIssue](https://cakebuild.net/api/Cake.Issues/Aliases/5BAA8171){target="_blank"} alias for creating issues in the build script. -* [ReadIssues](https://cakebuild.net/api/Cake.Issues/Aliases/2C801A33){target="_blank"} aliases for reading issues from an issue provider. -* Support for reading issues from multiple issue providers. -* Support for reading issues in multiple formats (Plain text, Markdown, HTML) if supported by issue provider. -* Support for creating links to file & location on source code hosting system (GitHub, Azure Repos, etc). -* Support for passing additional run information to identify specific runs. - -### Cake.Issues.Reporting - -Addin for creating reports providing the following functionality: - -* [CreateIssueReport](https://cakebuild.net/api/Cake.Issues.Reporting/Aliases/39023BBC){target="_blank"} - aliases for creating reports about issues. -* Support for creating reports with issues from multiple issue providers. - -### Cake.Issues.PullRequests - -Addin for writing issues as comments to pull requests providing the following functionality: - -* [ReportIssuesToPullRequest](https://cakebuild.net/api/Cake.Issues.PullRequests/Aliases/C0F2D0B8){target="_blank"} - aliases for writing issues as comments to pull requests. -* Support for reporting issues from multiple issue providers. -* Support for passing custom issue filter routines in `ReportIssuesToPullRequestSettings.IssueFilters`. -* Advanced support to limit number of maximum issues per run, across multiple runs or per issue provider by setting - `ReportIssuesToPullRequestSettings.MaxIssuesToPost`, `ReportIssuesToPullRequestSettings.MaxIssuesToPostAcrossRuns`, - `ReportIssuesToPullRequestSettings.MaxIssuesToPostForEachIssueProvider` and `ReportIssuesToPullRequestSettings.ProviderIssueLimits`. -* Returns all issues as provided by the issue providers and the issues reported to the pull request. - -Concrete pull request systems can implement optional capabilities which will provide the following functionality: - -* Filter by modified files ([BaseFilteringByModifiedFilesCapability](https://cakebuild.net/api/Cake.Issues.PullRequests/BaseFilteringByModifiedFilesCapability_1/){target="_blank"}) - * Filtering issues to only those related to changed files in a pull request. -* Check commit ID ([BaseCheckingCommitIdCapability](https://cakebuild.net/api/Cake.Issues.PullRequests/BaseCheckingCommitIdCapability_1/){target="_blank"}) - * Skipping posting of issues if checked source code is outdated by setting `ReportIssuesToPullRequestSettings.CommitId`. -* Support for discussion threads ([BaseDiscussionThreadsCapability](https://cakebuild.net/api/Cake.Issues.PullRequests/BaseDiscussionThreadsCapability_1/){target="_blank"}) - * Automatic resolving of issues fixed in subsequent commits. - * Automatic reopening of still existing issues which are already closed on pull request. - * Comparing issues by identifier to not rely on message or line numbers. - -## Supported Issue Providers - -See [Issue Provider Addins] for a list of currently supported analyzers and linters. - -## Supported Report Formats - -See [Report Format Addins] for a list of currently supported report output formats. - -## Supported Pull Request Systems - -See [Pull Request System Addins] for a list of currently supported pull request systems. - -[Supported Tools]: ../recipe/supported-tools.md -[Cake.Issues.Recipe]: ../recipe/overview.md -[Issue Provider Addins]: ../issue-providers/index.md -[Report Format Addins]: ../report-formats/index.md -[Pull Request System Addins]: ../pull-request-systems/index.md diff --git a/docs/docs/documentation/overview/introduction.md b/docs/docs/documentation/overview/introduction.md deleted file mode 100644 index 85df2480e..000000000 --- a/docs/docs/documentation/overview/introduction.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Introduction -description: Introduction ---- - -Do you want to break your build on JetBrains InspectCode issues? -Do you want to create nice reports for StyleCop issues in your code? -Do you want to have ESLint issues reported as comments to pull requests? -The Cake.Issues addins allows you to do this and much more. -Read issues from different analyzer or linters, create reports or add them as comments to pull requests. - -While some linting tools provide nice reporting capabilities, others don't. -Some build systems provide tasks to report issues into pull requests. -But if you're using another build system your out of luck. -Maybe you found a new nice linting tool which does exactly what you need, -but probably it won't integrate well with your existing other linting tools. - -The Cake.Issues addins tries to solve this, by providing a common and extensible infrastructure -for issue management in Cake build scripts. - -Unlike other Cake addins, the Cake Issues addin consists of over 15 different addins, -working together and providing over 75 aliases which can be used in Cake build scripts to work with issues. -The addins are built in a [modular architecture] and are providing different [extension points] which allows to easily -enhance them for supporting additional analyzers, linters, report formats and code review systems. - -!!! tip - To get started you can use one of the [Cake.Issues recipes], which bring support for different linters and - integration with build and pull request systems out-of-the box in a single and easy to use NuGet package. - -[:fontawesome-solid-video: Presentation](https://gitpitch.com/pascalberger/Cake.Issues-Presentation){ .md-button } - -[:fontawesome-solid-graduation-cap: Tutorials](../usage/index.md){ .md-button } - -[modular architecture]: ../fundamentals/architecture.md -[extension points]: ../extending/index.md -[Cake.Issues recipes]: ../recipe/overview.md diff --git a/docs/docs/documentation/overview/requirements.md b/docs/docs/documentation/overview/requirements.md deleted file mode 100644 index 0c67ccd3c..000000000 --- a/docs/docs/documentation/overview/requirements.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Requirements -description: Requirements for using Cake.Issues. ---- - -The requirements are listed in the [release notes] for any specific version - -[Release notes]: https://github.com/cake-contrib/Cake.Issues/releases diff --git a/docs/docs/documentation/pull-request-systems/azure-devops/features.md b/docs/docs/documentation/pull-request-systems/azure-devops/features.md index b7a0d33ea..50ff5fcb0 100644 --- a/docs/docs/documentation/pull-request-systems/azure-devops/features.md +++ b/docs/docs/documentation/pull-request-systems/azure-devops/features.md @@ -20,7 +20,7 @@ provides the following features. ## Supported capabilities The [Cake.Issues.PullRequests.AzureDevOps addin](https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/){target="_blank"} -supports all [Core features]. +supports the following capabilities. | | Capability | Remarks | |------------------|--------------------------------|--------------------------------| @@ -43,5 +43,4 @@ For detailed instructions how to connect using the different methods see [Setup ![Cake.Issues.PullRequests.AzureDevOps](cake.issues.pullrequests.azuredevops.png "Cake.Issues.PullRequests.AzureDevOps") [demo repository]: https://dev.azure.com/pberger/Cake.Issues-Demo -[Core features]: ../../overview/features.md#supported-core-functionality [Setup instructions]: setup.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f5a69a77a..97748da23 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -98,13 +98,9 @@ nav: - blog/index.md - Documentation: - Key concepts: - - Overview: - - Introduction: documentation/overview/introduction.md - - Features: documentation/overview/features.md - - Requirements: documentation/overview/requirements.md - - Fundamentals: - - Architecture: documentation/fundamentals/architecture.md - - Versioning: documentation/fundamentals/versioning.md + - Overview: documentation/overview.md + - How Cake Issues Works: documentation/how-cake-issues-works.md + - Features: documentation/features.md - How To Use: - Usage: - documentation/usage/index.md