From cc608ef5af22867dac6067f9cd56e47efae77261 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Mon, 8 Feb 2021 15:16:24 +0100 Subject: [PATCH 1/6] AzureDevOpsDsc: Support publish wiki documentation --- CHANGELOG.md | 15 +++++++++ RequiredModules.psd1 | 5 +-- build.yaml | 20 ++++++++---- source/Classes/010.AzDevOpsProject.ps1 | 3 ++ source/WikiSource/Home.md | 45 ++++++++++++++++++++++++++ 5 files changed, 78 insertions(+), 10 deletions(-) create mode 100644 source/WikiSource/Home.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 122c8f459..87335105d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,9 +22,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 'prefix.ps1' ([issue #12](https://github.com/dsccommunity/AzureDevOpsDsc/issues/12)). - AzureDevOpsDsc.Common - Added 'wrapper' functionality around the [Azure DevOps REST API](https://docs.microsoft.com/en-us/rest/api/azure/devops/) +- Added pipeline support for publish markdown content to the GitHub repository + wiki ([issue #15](https://github.com/dsccommunity/AzureDevOpsDsc/issues/15)). + This will publish the markdown documentation that is generated bu the + build pipeline. +- Added new source folder `WikiSource`. Every markdown file in the folder + `WikiSource` will be published to the GitHub repository wiki. The markdown + file `Home.md` will be updated with the correct module version on each + publish to gallery (including preview). ### Changed - Enabled integration tests against https://dev.azure.com/azuredevopsdsc/ (see comment https://github.com/dsccommunity/AzureDevOpsDsc/issues/9#issuecomment-766375424 for more information). +- Updated pipeline file `RequiredModules.ps1` to latest pipeline pattern. +- Updated pipeline file `build.yaml` to latest pipeline pattern. + +### Fixed + +- AzDevOpsProject + - Added description to the comment-based help. diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index dd32e5874..1304808d1 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -1,11 +1,8 @@ @{ - # Set up a mini virtual environment... PSDependOptions = @{ AddToPath = $true Target = 'output\RequiredModules' - Parameters = @{ - Repository = '' - } + Parameters = @{} } InvokeBuild = 'latest' diff --git a/build.yaml b/build.yaml index fae560882..1b7b0e49e 100644 --- a/build.yaml +++ b/build.yaml @@ -52,7 +52,7 @@ BuildWorkflow: publish: - Publish_release_to_GitHub - publish_module_to_gallery - + - Publish_GitHub_Wiki_Content #################################################### # PESTER Configuration # @@ -80,11 +80,6 @@ DscTest: ExcludeModuleFile: MainGitBranch: main -Resolve-Dependency: - Gallery: 'PSGallery' - AllowPrerelease: false - Verbose: false - ModuleBuildTasks: Sampler: - '*.build.Sampler.ib.tasks' @@ -108,3 +103,16 @@ GitHubConfig: GitHubConfigUserName: dscbot GitHubConfigUserEmail: dsccommunity@outlook.com UpdateChangelogOnPrerelease: false + +#################################################### +# DscResource.DocGenerator Configuration # +#################################################### +DscResource.DocGenerator: + Generate_Conceptual_Help: + MarkdownCodeRegularExpression: + - '\`(.+?)\`' # Match inline code-block + - '\\(\\)' # Match escaped backslash + - '\[[^\[]+\]\((.+?)\)' # Match markdown URL + - '_(.+?)_' # Match Italic (underscore) + - '\*\*(.+?)\*\*' # Match bold + - '\*(.+?)\*' # Match Italic (asterisk) diff --git a/source/Classes/010.AzDevOpsProject.ps1 b/source/Classes/010.AzDevOpsProject.ps1 index 5c9a2af83..2b941573f 100644 --- a/source/Classes/010.AzDevOpsProject.ps1 +++ b/source/Classes/010.AzDevOpsProject.ps1 @@ -2,6 +2,9 @@ .SYNOPSIS A DSC Resource for Azure DevOps that represents the 'Project' resource. + .DESCRIPTION + A DSC Resource for Azure DevOps that represents the 'Project' resource. + .PARAMETER ProjectId The 'Id' of the Azure DevOps, 'Project' resource. diff --git a/source/WikiSource/Home.md b/source/WikiSource/Home.md new file mode 100644 index 000000000..a1cf946e9 --- /dev/null +++ b/source/WikiSource/Home.md @@ -0,0 +1,45 @@ +# Welcome to the AzureDevOpsDsc wiki + +*AzureDevOpsDsc v#.#.#* + +Here you will find all the information you need to make use of the AzureDevOpsDsc +DSC resources in the latest release. This includes details of the resources +that are available, current capabilities, known issues, and information to +help plan a DSC based implementation of AzureDevOpsDsc. + +Please leave comments, feature requests, and bug reports for this module in +the [issues section](https://github.com/dsccommunity/AzureDevOpsDsc/issues) +for this repository. + +## Getting started + +To get started either: + +- Install from the PowerShell Gallery using PowerShellGet by running the + following command: + +```powershell +Install-Module -Name AzureDevOpsDsc -Repository PSGallery +``` + +- Download AzureDevOpsDsc from the [PowerShell Gallery](https://www.powershellgallery.com/packages/AzureDevOpsDsc) + and then unzip it to one of your PowerShell modules folders (such as + `$env:ProgramFiles\WindowsPowerShell\Modules`). + +To confirm installation, run the below command and ensure you see the AzureDevOpsDsc +DSC resources available: + +```powershell +Get-DscResource -Module AzureDevOpsDsc +``` + +## Prerequisites + +The minimum Windows Management Framework (PowerShell) version required is 5.0 +or higher, which ships with Windows 10 or Windows Server 2016, +but can also be installed on Windows 7 SP1, Windows 8.1, Windows Server 2012, +and Windows Server 2012 R2. + +## Change log + +A full list of changes in each version can be found in the [change log](https://github.com/dsccommunity/AzureDevOpsDsc/blob/main/CHANGELOG.md). From cf4f054264c79d97714f781dc46352a7e01b4565 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Mon, 8 Feb 2021 15:25:35 +0100 Subject: [PATCH 2/6] Fix CHANGELOG.md --- CHANGELOG.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87335105d..013475837 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,16 +20,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Removed `Examples` directory from being output in packaged module ([issue #11](https://github.com/dsccommunity/AzureDevOpsDsc/issues/11)). - Moved 'Ensure' and 'RequiredAction' enums into 'Enum' directory and out of 'prefix.ps1' ([issue #12](https://github.com/dsccommunity/AzureDevOpsDsc/issues/12)). + - Added pipeline support for publish markdown content to the GitHub repository + wiki ([issue #15](https://github.com/dsccommunity/AzureDevOpsDsc/issues/15)). + This will publish the markdown documentation that is generated bu the + build pipeline. + - Added new source folder `WikiSource`. Every markdown file in the folder + `WikiSource` will be published to the GitHub repository wiki. The markdown + file `Home.md` will be updated with the correct module version on each + publish to gallery (including preview). - AzureDevOpsDsc.Common - Added 'wrapper' functionality around the [Azure DevOps REST API](https://docs.microsoft.com/en-us/rest/api/azure/devops/) -- Added pipeline support for publish markdown content to the GitHub repository - wiki ([issue #15](https://github.com/dsccommunity/AzureDevOpsDsc/issues/15)). - This will publish the markdown documentation that is generated bu the - build pipeline. -- Added new source folder `WikiSource`. Every markdown file in the folder - `WikiSource` will be published to the GitHub repository wiki. The markdown - file `Home.md` will be updated with the correct module version on each - publish to gallery (including preview). ### Changed From 4f0d667d37918812605bea085c39d0344f98a476 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Mon, 8 Feb 2021 15:26:51 +0100 Subject: [PATCH 3/6] Fix CHANGELOG.md --- CHANGELOG.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 013475837..6d8a18478 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,11 +33,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- Enabled integration tests against https://dev.azure.com/azuredevopsdsc/ (see - comment https://github.com/dsccommunity/AzureDevOpsDsc/issues/9#issuecomment-766375424 - for more information). -- Updated pipeline file `RequiredModules.ps1` to latest pipeline pattern. -- Updated pipeline file `build.yaml` to latest pipeline pattern. +- AzureDevOpsDsc + - Enabled integration tests against https://dev.azure.com/azuredevopsdsc/ (see + comment https://github.com/dsccommunity/AzureDevOpsDsc/issues/9#issuecomment-766375424 + for more information). + - Updated pipeline file `RequiredModules.ps1` to latest pipeline pattern. + - Updated pipeline file `build.yaml` to latest pipeline pattern. ### Fixed From 16024d6cd673b85f25fb181625af1395c5beaedb Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Mon, 8 Feb 2021 15:36:18 +0100 Subject: [PATCH 4/6] Update parameter SourceControlType --- CHANGELOG.md | 6 ++++++ source/Classes/010.AzDevOpsProject.ps1 | 6 ++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d8a18478..d480d6506 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 for more information). - Updated pipeline file `RequiredModules.ps1` to latest pipeline pattern. - Updated pipeline file `build.yaml` to latest pipeline pattern. +- AzDevOpsProject + - Added a validate set to the parameter `SourceControlType` to (for now) + limit the parameter to the values `Git` and `Tfvc`. + - Update comment-based help to remove text which the valid values are + since that is now add automatically to the documentation (conceptual + help and wiki documentation). ### Fixed diff --git a/source/Classes/010.AzDevOpsProject.ps1 b/source/Classes/010.AzDevOpsProject.ps1 index 2b941573f..5d64eb39a 100644 --- a/source/Classes/010.AzDevOpsProject.ps1 +++ b/source/Classes/010.AzDevOpsProject.ps1 @@ -15,9 +15,10 @@ The 'Description' of the Azure DevOps, 'Project' resource. .PARAMETER SourceControlType - The 'SourceControlType' of the Azure DevOps, 'Project' resource. Valid options are 'Git' and 'Tfvc'. + The 'SourceControlType' of the Azure DevOps, 'Project' resource. - If the 'Project' resource already exists in Azure DevOps, the 'SourceControlType' cannot be changed to another type. + If the 'Project' resource already exists in Azure DevOps, the parameter + `SourceControlType` cannot be used to changed to another type. #> [DscResource()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSDSCStandardDSCFunctionsInResource', '', Justification='Test() and Set() method are inherited from base, "AzDevOpsDscResourceBase" class')] @@ -36,6 +37,7 @@ class AzDevOpsProject : AzDevOpsDscResourceBase [System.String]$ProjectDescription [DscProperty()] + [ValidateSet('Git', 'Tfvc')] [System.String]$SourceControlType From 9c48d91d2094822b4f20c04f5c4d7b99398fbc93 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Tue, 9 Feb 2021 14:54:04 +0100 Subject: [PATCH 5/6] Fix unit test --- build.yaml | 2 +- .../AzDevOpsProject/AzDevOpsProject.Tests.ps1 | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/build.yaml b/build.yaml index 1b7b0e49e..46731b217 100644 --- a/build.yaml +++ b/build.yaml @@ -63,7 +63,7 @@ Pester: ExcludeFromCodeCoverage: - Modules/DscResource.Common Script: - - tests/Integration + # Only run on unit test on './build.ps1 -Task test' - tests/Unit ExcludeTag: Tag: diff --git a/tests/Unit/DSCClassResources/AzDevOpsProject/AzDevOpsProject.Tests.ps1 b/tests/Unit/DSCClassResources/AzDevOpsProject/AzDevOpsProject.Tests.ps1 index a818a34f6..0decd03ac 100644 --- a/tests/Unit/DSCClassResources/AzDevOpsProject/AzDevOpsProject.Tests.ps1 +++ b/tests/Unit/DSCClassResources/AzDevOpsProject/AzDevOpsProject.Tests.ps1 @@ -31,8 +31,7 @@ InModuleScope 'AzureDevOpsDsc' { 'Pat', 'ProjectId', 'ProjectName', - 'ProjectDescription', - 'SourceControlType' + 'ProjectDescription' ) $testCasesValidPropertyNames = $validPropertyNames | ForEach-Object { @{ @@ -41,6 +40,11 @@ InModuleScope 'AzureDevOpsDsc' { } } + $testCasesValidPropertyNames += @{ + PropertyName = 'SourceControlType' + PropertyValue = 'Git' + } + Context 'When creating a new instance of the class' { It 'Should not throw' { From 18868ad83991e67bae240cf74644858ab15b2f9f Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Thu, 11 Feb 2021 19:57:39 +0100 Subject: [PATCH 6/6] Fix review comment at r1 --- source/Classes/010.AzDevOpsProject.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Classes/010.AzDevOpsProject.ps1 b/source/Classes/010.AzDevOpsProject.ps1 index 5d64eb39a..4dea38bbc 100644 --- a/source/Classes/010.AzDevOpsProject.ps1 +++ b/source/Classes/010.AzDevOpsProject.ps1 @@ -18,7 +18,7 @@ The 'SourceControlType' of the Azure DevOps, 'Project' resource. If the 'Project' resource already exists in Azure DevOps, the parameter - `SourceControlType` cannot be used to changed to another type. + `SourceControlType` cannot be used to change to another type. #> [DscResource()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSDSCStandardDSCFunctionsInResource', '', Justification='Test() and Set() method are inherited from base, "AzDevOpsDscResourceBase" class')]