From 891384f31a3366e1c7e0bad87d0f4b099992d1f6 Mon Sep 17 00:00:00 2001 From: Hennadii Lutsyshyn Date: Sat, 30 Mar 2024 02:19:58 +0200 Subject: [PATCH] fix: Added more information into documentation for targets. --- Directory.Build.props | 9 +++------ README.md | 2 +- src/Heleonix.Build/Heleonix.Build.csproj | 6 +++--- src/Heleonix.Build/Program.cs | 2 ++ .../Schemas/Targets/Hx_ChangeLog.xsd | 16 +++++++++++++++- .../Targets/Hx_ChangeLog_GitHubCommit.xsd | 12 ++++++++++++ src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd | 8 ++++++++ .../Schemas/Targets/Hx_DocFX_Git.xsd | 11 +++++++++++ .../Schemas/Targets/Hx_ExtentReport.xsd | 9 +++++++++ .../Schemas/Targets/Hx_NetBuild.xsd | 13 +++++++++++++ .../Schemas/Targets/Hx_NetNugetPush.xsd | 11 +++++++++++ .../Schemas/Targets/Hx_NetTest.xsd | 16 ++++++++++++++++ .../Schemas/Targets/Hx_NetValidate.xsd | 12 +++++++++++- .../Schemas/Targets/Hx_Release_GitHub.xsd | 8 ++++++++ .../Schemas/Targets/Hx_ReportGenerator.xsd | 8 ++++++++ .../Schemas/Targets/Hx_TrxReport.xsd | 8 ++++++++ .../Heleonix.Build.Tests.ExeMock.csproj | 4 ++-- test/Heleonix.Build.Tests.ExeMock/Program.cs | 2 +- .../Heleonix.Build.Tests.csproj | 8 ++++---- .../Tasks/Hx_DirectoryCleanTests.cs | 2 +- 20 files changed, 147 insertions(+), 20 deletions(-) diff --git a/Directory.Build.props b/Directory.Build.props index 0b13fe7..52239ee 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -12,23 +12,20 @@ https://heleonix.github.io/docs/Heleonix.Build/ https://raw.githubusercontent.com/Heleonix/docs/master/images/heleonix-logos/Heleonix-logo-128x128.jpg - true - .\ - .\ + NU5048;SA0001 LICENSE README.md - - + + enable latest true - SA0001 en-US en-US diff --git a/README.md b/README.md index 43c8129..59aed90 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ So, if you follow well-known standards too, you do not even neeed to write custo 4. [Request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from the code owner 5. Once approved, merge your Pull Request via [Squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) - > [!IMPORTANT] + > **IMPORTANT** > While merging, enter a [Conventional Commits](https://www.conventionalcommits.org/) commit message. > This commit message will be used in automatically generated [Github Release Notes](https://github.com/Heleonix/Heleonix.Build/releases) > and [NuGet Release Notes](https://www.nuget.org/packages/Heleonix.Build/#releasenotes-body-tab) diff --git a/src/Heleonix.Build/Heleonix.Build.csproj b/src/Heleonix.Build/Heleonix.Build.csproj index 7d267d7..1949b57 100644 --- a/src/Heleonix.Build/Heleonix.Build.csproj +++ b/src/Heleonix.Build/Heleonix.Build.csproj @@ -37,15 +37,15 @@ - + - + - + diff --git a/src/Heleonix.Build/Program.cs b/src/Heleonix.Build/Program.cs index b73675d..27682db 100644 --- a/src/Heleonix.Build/Program.cs +++ b/src/Heleonix.Build/Program.cs @@ -54,7 +54,9 @@ public static int Main(string[] args) dotnetExePath = args[i + 1]; +#pragma warning disable S127 // "for" loop stop conditions should be invariant i += 1; +#pragma warning restore S127 // "for" loop stop conditions should be invariant } else { diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd index 23b39eb..1425237 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd @@ -30,6 +30,20 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + The virtual target for variations of real targets to generate change logs from different sources + and in different ways to be further used in versioning of builds, generation of release notes etc. + Variations of this target should generate at least the 'semver.txt' containing the new semantic version + in the format 'Major.Minor.Patch' of the product to be released based on discovered changes, + and generate two files: 'ReleaseNotes.md' and 'ReleaseNotes.txt' containing textual descriptions + of discovered changes, which can be used by other targets, i.e. by the 'Hx_NetBuild' while building a solution + with enabled NuGet package generation, or by the 'Hx_Release_GitHub' while creating a release on GitHub etc. + + + + @@ -41,7 +55,7 @@ Example custom property that allows string content only - The list of Razor *.cshtml template files to generates change logs with using the Hx_FileRazorGenerate task. + The list of Razor *.cshtml template files to generate change logs using the Hx_FileRazorGenerate task. Default are two templates: 'ReleaseNotes.md.cshtml' and 'ReleaseNotes.txt.cshtml' from the Heleonix.Build. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd index 875b509..7fa931a 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd @@ -30,6 +30,18 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + Calculates a new release version and generates change log files from GitHub commit messages, + which are parsed with regular expressions. By default, it calculates a new release semantic version and + change log messages using regular expressions for parsing. + By default it recognizes https://www.conventionalcommits.org, but it's welcome to specify custom regular + expressions to recognize custom project/company specific formats of commit messages. + + + + A GitHub access token to authorize to the GitHub Releases API. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd index 296f717..272a120 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd @@ -30,6 +30,14 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + The virtual target for variations of real targets to generate documentation stored as a repository. + + + + A path to the DocFX artifacts directory. Default is '$Hx_Run_ArtifactsDir/DocFX'. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_DocFX_Git.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_DocFX_Git.xsd index 265515e..7d9d7ef 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_DocFX_Git.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_DocFX_Git.xsd @@ -30,6 +30,17 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + The target to generate documentation created as a Docfx project. + The target checks out a branch from a git repository containing a Docfx project, runs the 'docfx metadata' command, + then runs the 'docfx build', then commits generated changes with the specified $Hx_DocFX_Message and pushes + changes back to the remote repository. + + + + diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_ExtentReport.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_ExtentReport.xsd index 5fa27c7..33715e7 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_ExtentReport.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_ExtentReport.xsd @@ -30,6 +30,15 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + The target generates test reports using https://www.extentreports.com. + Under the hood this target uses the https://www.nuget.org/packages/extent package. + + + + diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_NetBuild.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_NetBuild.xsd index 96b9097..1f3b8c9 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_NetBuild.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_NetBuild.xsd @@ -30,6 +30,19 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + The target performs building of the specified solution file. + It deletes specified extra files, deletes speified extra folders, cleans specified extra folders, + runs the 'Restore' and then 'Clean' MSBuild targets, runs 'Restore' and then 'Build' MSBuild targets. + Afterwards, the target copies .sln, 'bin' and 'obj' folders, *.props, *.*proj and custom artifacts files + to the artifacts directory, which then can be uploaded to artifacts storage and then re-used by other targets, + i.e. 'Hx_NetTest', 'Hx_NetNugetPush' etc. + + + + diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_NetNugetPush.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_NetNugetPush.xsd index a8c348a..116cc61 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_NetNugetPush.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_NetNugetPush.xsd @@ -30,6 +30,17 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + Publishes specified package files to the specified NuGet registry using the 'dotnet nuget push' command. + If no package files are specified, the target tries to find them in the $Hx_NetBuild_ArtifactsDir + and if package files are not found, the target executes the MSBuild 'Pack' target against the solution file + found in the $Hx_NetBuild_ArtifactsDir to generate package files. + + + + diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_NetTest.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_NetTest.xsd index 5bd49de..71ca435 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_NetTest.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_NetTest.xsd @@ -30,6 +30,22 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + Runs the 'dotnet test' command against the specified test files. By default, runs 'XPlat Code Coverage' + with NUnit test logger https://www.nuget.org/packages/NunitXml.TestLogger. + The target internally converts the generated test coverage into XMLSummary using the 'ReportGenerator' tool, + and verifies the specified thresholds of source code coverage. + This target also replaces source code paths using the specified regular expressions + in generated *.info, *.xml, *.json files with persistent paths, + i.e. paths of source code files on the particular build agent with corresponding GitHub urls, + so generated test or coverage reports become portable. Such solution is flexible to support different + formats of test or coverage files and different persistent paths, like GitHub, GitLab, SVN etc. + + + + diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_NetValidate.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_NetValidate.xsd index dd414aa..5e06ba9 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_NetValidate.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_NetValidate.xsd @@ -30,6 +30,16 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + This target verifies that every file satisfies all the regular expressions specified in its metadata. + This is useful to verify that projects reference specific packages, + or projects contain specific MSBuild properties, or any custom file contains required content. + + + + Regular expression options to use when executing validation for each @Hx_NetValidate_Files. @@ -39,7 +49,7 @@ Example custom property that allows string content only - The list of files with regular expressions defined as metadata to validate. + The list of files with regular expressions defined as metadata (metadata keys can be named in a free form) to validate. Defaults are project files, which must have the following packages: codecracker.CSharp, Microsoft.CodeAnalysis.NetAnalyzers, SecurityCodeScan.VS2019, SonarAnalyzer.CSharp, StyleCop.Analyzers. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_Release_GitHub.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_Release_GitHub.xsd index a2e193f..b42e65b 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_Release_GitHub.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_Release_GitHub.xsd @@ -30,6 +30,14 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + Creates a release on GitHub using GitHub API. For example: https://github.com/Heleonix/Heleonix.Build/releases. + + + + A GitHub access token to authorize to the GitHub Releases API. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_ReportGenerator.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_ReportGenerator.xsd index 8025082..e71014f 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_ReportGenerator.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_ReportGenerator.xsd @@ -30,6 +30,14 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + This target runs https://www.nuget.org/packages/dotnet-reportgenerator-globaltool against coverage results files. + + + + A path to the ReportGenerator artifacts directory. Default is '$Hx_Run_ArtifactsDir/ReportGenerator'. diff --git a/src/Heleonix.Build/Schemas/Targets/Hx_TrxReport.xsd b/src/Heleonix.Build/Schemas/Targets/Hx_TrxReport.xsd index de03250..a63e2a8 100644 --- a/src/Heleonix.Build/Schemas/Targets/Hx_TrxReport.xsd +++ b/src/Heleonix.Build/Schemas/Targets/Hx_TrxReport.xsd @@ -30,6 +30,14 @@ Example custom property that allows string content only elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003" xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + This target is not implemented yet, but the idea is to generate HTML test reports from the *.trx files. + + + + A path to the TrxReport artifacts directory. Default is '$Hx_Run_ArtifactsDir/TrxReport' diff --git a/test/Heleonix.Build.Tests.ExeMock/Heleonix.Build.Tests.ExeMock.csproj b/test/Heleonix.Build.Tests.ExeMock/Heleonix.Build.Tests.ExeMock.csproj index 757573a..8eabd2f 100644 --- a/test/Heleonix.Build.Tests.ExeMock/Heleonix.Build.Tests.ExeMock.csproj +++ b/test/Heleonix.Build.Tests.ExeMock/Heleonix.Build.Tests.ExeMock.csproj @@ -8,10 +8,10 @@ - + - + diff --git a/test/Heleonix.Build.Tests.ExeMock/Program.cs b/test/Heleonix.Build.Tests.ExeMock/Program.cs index ff036ac..8a3de6b 100644 --- a/test/Heleonix.Build.Tests.ExeMock/Program.cs +++ b/test/Heleonix.Build.Tests.ExeMock/Program.cs @@ -3,7 +3,7 @@ // Licensed under the MIT license. See LICENSE file in the repository root for full license information. // -if (args.Any(a => a.Contains("ERROR"))) +if (Array.Exists(args, a => a.Contains("ERROR"))) { Console.Error.Write("ERROR details"); diff --git a/test/Heleonix.Build.Tests/Heleonix.Build.Tests.csproj b/test/Heleonix.Build.Tests/Heleonix.Build.Tests.csproj index 0e3d6a7..6736d5d 100644 --- a/test/Heleonix.Build.Tests/Heleonix.Build.Tests.csproj +++ b/test/Heleonix.Build.Tests/Heleonix.Build.Tests.csproj @@ -31,17 +31,17 @@ - - + + - + - + diff --git a/test/Heleonix.Build.Tests/Tasks/Hx_DirectoryCleanTests.cs b/test/Heleonix.Build.Tests/Tasks/Hx_DirectoryCleanTests.cs index 6f7f39d..0caf311 100644 --- a/test/Heleonix.Build.Tests/Tasks/Hx_DirectoryCleanTests.cs +++ b/test/Heleonix.Build.Tests/Tasks/Hx_DirectoryCleanTests.cs @@ -65,7 +65,7 @@ public static void Execute() foreach (var dir in directories) { - Assert.That(task.CleanedDirs.Any(item => item == dir)); + Assert.That(Array.Exists(task.CleanedDirs, item => item == dir)); Assert.That(Directory.GetFiles(dir), Has.Length.Zero); Assert.That(Directory.GetDirectories(dir), Has.Length.Zero); }