diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..c586361 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "MD024": { + "siblings_only": true + } +} diff --git a/.vscode/settings.json b/.vscode/settings.json index a139506..d237442 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -2,16 +2,19 @@ //-------- Files configuration -------- // When enabled, will trim trailing whitespace when you save a file. "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true, + "editor.insertSpaces": true, + // -------- Search configuration -------- + // Exclude the Output folder from search results. "search.exclude": { - "Release": true, - "Output": true, + "Output/**": true, }, - "editor.tabSize": 4, //-------- PowerShell Configuration -------- // Use a custom PowerShell Script Analyzer settings file for this workspace. // Relative paths for this setting are always relative to the workspace root dir. "powershell.scriptAnalysis.settingsPath": "ScriptAnalyzerSettings.psd1", //----------Code Formatting ---------------- "powershell.codeFormatting.preset": "OTBS", - "editor.formatOnSave": true + "editor.formatOnSave": true, + "powershell.scriptAnalysis.enable": true } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index c5e7014..b75878a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,53 +1,72 @@ -# Plaster Release History +# Change Log -## 2.0.0 - 2025-06-18 +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). + +## [2.0.0] - 2025-06-18 ### Major Release - Plaster 2.0 -This is a major release that modernizes Plaster for PowerShell 7.x while maintaining full backward compatibility with existing templates and workflows. +This is a major release that modernizes Plaster for PowerShell 7.x while +maintaining full backward compatibility with existing templates and workflows. ### BREAKING CHANGES - **Minimum PowerShell Version**: Updated from 3.0 to 5.1 -- **Build System**: Replaced psake with modern InvokeBuild for better cross-platform support - **Test Framework**: Updated to Pester 5.x (breaking change for test authors) -- **Default Encoding**: Changed from 'Default' to 'UTF8-NoBOM' for better cross-platform compatibility +- **Default Encoding**: Changed from 'Default' to 'UTF8-NoBOM' for better + cross-platform compatibility ### NEW FEATURES #### PowerShell 7.x Full Support + - **Cross-Platform Compatibility**: Full support for Windows, Linux, and macOS -- **PowerShell Core Optimization**: Improved performance and reliability on PowerShell 7.x -- **Platform Detection**: Enhanced platform-specific functionality and path handling +- **PowerShell Core Optimization**: Improved performance and reliability on + PowerShell 7.x +- **Platform Detection**: Enhanced platform-specific functionality and path + handling #### Modern Development Practices -- **Enhanced Error Handling**: Comprehensive error handling with detailed logging + +- **Enhanced Error Handling**: Comprehensive error handling with detailed + logging - **Parameter Validation**: Modern PowerShell parameter validation attributes -- **Type Safety**: Improved type safety using PowerShell classes and `using` statements +- **Type Safety**: Improved type safety using PowerShell classes and `using` + statements - **Logging System**: Built-in logging system with configurable levels #### Build and Development + - **Modern Build System**: InvokeBuild-based build system replacing legacy psake - **Pester 5.x Support**: Updated test framework with modern Pester 5.x syntax - **Cross-Platform CI/CD**: GitHub Actions workflow supporting all platforms -- **Code Coverage**: Integrated code coverage reporting with configurable thresholds +- **Code Coverage**: Integrated code coverage reporting with configurable + thresholds - **Static Analysis**: Enhanced PSScriptAnalyzer integration with modern rules ### IMPROVEMENTS #### Performance + - **Faster Module Loading**: Optimized module loading and reduced startup time - **Memory Usage**: Improved memory usage and garbage collection -- **Template Processing**: Enhanced template processing performance on large projects +- **Template Processing**: Enhanced template processing performance on large + projects - **Cross-Platform I/O**: Optimized file operations for different platforms #### Developer Experience -- **Better Error Messages**: More descriptive error messages with actionable guidance + +- **Better Error Messages**: More descriptive error messages with actionable + guidance - **Enhanced Debugging**: Improved debug output and verbose logging - **IntelliSense Support**: Better parameter completion and help text - **Modern PowerShell Features**: Leverages PowerShell 5.1+ and 7.x features #### Cross-Platform Enhancements + - **Path Normalization**: Automatic path separator handling across platforms - **Encoding Handling**: Consistent UTF-8 encoding with BOM handling - **Platform-Specific Defaults**: Smart defaults based on operating system @@ -56,18 +75,24 @@ This is a major release that modernizes Plaster for PowerShell 7.x while maintai ### BUG FIXES #### Core Issues -- **XML Schema Validation**: Fixed .NET Core XML schema validation issues ([#107](https://github.com/PowerShellOrg/Plaster/issues/107)) -- **Constrained Runspace**: Resolved PowerShell 7.x constrained runspace compatibility + +- **XML Schema Validation**: Fixed .NET Core XML schema validation issues + ([#107](https://github.com/PowerShellOrg/Plaster/issues/107)) +- **Constrained Runspace**: Resolved PowerShell 7.x constrained runspace + compatibility - **Path Resolution**: Fixed absolute vs relative path handling across platforms -- **Parameter Store**: Corrected parameter default value storage on non-Windows platforms +- **Parameter Store**: Corrected parameter default value storage on non-Windows + platforms #### Template Processing + - **Variable Substitution**: Fixed edge cases in parameter substitution - **Conditional Logic**: Improved reliability of condition evaluation - **File Encoding**: Resolved encoding issues with template files - **Directory Creation**: Fixed recursive directory creation on Unix systems #### Module Loading + - **Import Errors**: Resolved module import issues on PowerShell Core - **Dependency Resolution**: Fixed module dependency loading order - **Resource Loading**: Improved localized resource loading reliability @@ -75,35 +100,42 @@ This is a major release that modernizes Plaster for PowerShell 7.x while maintai ### MIGRATION GUIDE #### For Template Authors + 1. **No Changes Required**: Existing XML templates work without modification 2. **Encoding**: Consider updating templates to use UTF-8 encoding 3. **Testing**: Update any custom tests to use Pester 5.x syntax #### For Template Users + 1. **PowerShell Version**: Ensure PowerShell 5.1 or higher is installed 2. **Module Update**: Use `Update-Module Plaster` to get version 2.0 3. **Workflows**: No changes required to existing Invoke-Plaster usage #### For Contributors + 1. **Build System**: Use `./build.ps1` instead of psake commands 2. **Tests**: Update to Pester 5.x syntax and configuration -3. **Development**: Follow new coding standards and use modern PowerShell features +3. **Development**: Follow new coding standards and use modern PowerShell + features ### INTERNAL CHANGES #### Code Quality + - **PSScriptAnalyzer**: Updated to latest rules and best practices - **Code Coverage**: Achieved >80% code coverage across all modules - **Documentation**: Comprehensive inline documentation and examples - **Type Safety**: Added parameter validation and type constraints #### Architecture + - **Module Structure**: Reorganized for better maintainability - **Error Handling**: Centralized error handling and logging - **Resource Management**: Improved resource cleanup and disposal - **Platform Abstraction**: Abstracted platform-specific functionality #### Testing + - **Test Coverage**: Comprehensive test suite covering all platforms - **Integration Tests**: Added end-to-end integration testing - **Performance Tests**: Benchmarking for performance regression detection @@ -111,15 +143,17 @@ This is a major release that modernizes Plaster for PowerShell 7.x while maintai ### ACKNOWLEDGMENTS -Special thanks to the PowerShell community for their patience during the transition and to all contributors who helped modernize Plaster for the PowerShell 7.x era. +Special thanks to the PowerShell community for their patience during the +transition and to all contributors who helped modernize Plaster for the +PowerShell 7.x era. ### COMPATIBILITY MATRIX -| PowerShell Version | Windows | Linux | macOS | Status | -|-------------------|---------|-------|-------|---------| -| 5.1 (Desktop) | ✅ | ❌ | ❌ | Fully Supported | -| 7.0+ (Core) | ✅ | ✅ | ✅ | Fully Supported | -| 3.0-5.0 | ❌ | ❌ | ❌ | No Longer Supported | +| PowerShell Version | Windows | Linux | macOS | Status | +|--------------------|---------|-------|-------|---------------------| +| 5.1 (Desktop) | ✅ | ❌ | ❌ | Fully Supported | +| 7.0+ (Core) | ✅ | ✅ | ✅ | Fully Supported | +| 3.0-5.0 | ❌ | ❌ | ❌ | No Longer Supported | --- @@ -127,43 +161,55 @@ Special thanks to the PowerShell community for their patience during the transit ### Fixed -- Write destination path with Write-Host so it doesn't add extra output when -PassThru specified - [#326](https://github.com/PowerShell/Plaster/issues/326). +- Write destination path with Write-Host so it doesn't add extra output when + -PassThru specified [#326](https://github.com/PowerShell/Plaster/issues/326). ### Changed -- Updated PSScriptAnalyzerSettings.psd1 template file to sync w/latest in vscode-powershell examples. -- Text parameter with default value where condition evaluates to false returns default value. +- Updated PSScriptAnalyzerSettings.psd1 template file to sync w/latest in + vscode-powershell examples. +- Text parameter with default value where condition evaluates to false returns + default value. ## 1.1.1 - 2017-10-26 ### Fixed -- Added $IsMacOS variable to constrained runspace [#291](https://github.com/PowerShell/Plaster/issues/291). -- Added missing .cat file from 1.1.0 release [#292](https://github.com/PowerShell/Plaster/issues/292). +- Added $IsMacOS variable to constrained runspace + [#291](https://github.com/PowerShell/Plaster/issues/291). +- Added missing .cat file from 1.1.0 release + [#292](https://github.com/PowerShell/Plaster/issues/292). ## 1.1.0 - 2017-10-25 ### Fixed -- Fixed prompt errors when prompt text null or empty [#236](https://github.com/PowerShell/Plaster/issues/236). -- Fixed New Module Script template's Test task which fails to run on x64 Visual Studio Code. -- Fixed Test-PlasterManifest on non-Windows running .NET Core 2.0 failed with path using \ instead of /. - Thanks to [@elmundio87](https://github.com/elmundio87) via PR [#282](https://github.com/PowerShell/Plaster/pull/282) +- Fixed prompt errors when prompt text null or empty + [#236](https://github.com/PowerShell/Plaster/issues/236). +- Fixed New Module Script template's Test task which fails to run on x64 Visual + Studio Code. +- Fixed Test-PlasterManifest on non-Windows running .NET Core 2.0 failed with + path using \ instead of /. Thanks to + [@elmundio87](https://github.com/elmundio87) via PR + [#282](https://github.com/PowerShell/Plaster/pull/282) ### Added -- Added constrained runspace cmdlet: Out-String [#235](https://github.com/PowerShell/Plaster/issues/236). -- Added constrained runspace variables: PSVersionTable and on >= PS v6 IsLinux, IsOSX and IsWindows [#239](https://github.com/PowerShell/Plaster/issues/239). -- The parameter element now supports a condition attribute so that prompting for parameters can be - conditional based on environmental factors (such as OS) or answers to previous parameter prompts. - This allows template authors to build a "dynamic" set of prompts. -- Added constrained runspace cmdlet: Compare-Object [#286](https://github.com/PowerShell/Plaster/issues/287). +- Added constrained runspace cmdlet: Out-String + [#235](https://github.com/PowerShell/Plaster/issues/236). +- Added constrained runspace variables: PSVersionTable and on >= PS v6 IsLinux, + IsOSX and IsWindows [#239](https://github.com/PowerShell/Plaster/issues/239). +- The parameter element now supports a condition attribute so that prompting for + parameters can be conditional based on environmental factors (such as OS) or + answers to previous parameter prompts. This allows template authors to build a + "dynamic" set of prompts. +- Added constrained runspace cmdlet: Compare-Object + [#286](https://github.com/PowerShell/Plaster/issues/287). ### Changed -- Simplified New Module Script template user choices i.e. removed prompt for adding Pester test. - The test is now always added. +- Simplified New Module Script template user choices i.e. removed prompt for + adding Pester test. The test is now always added. ## 1.0.1 - 2016-12-16 @@ -175,15 +221,20 @@ Special thanks to the PowerShell community for their patience during the transit ## 0.3.0 - 2016-11-05 -- Updated build script with support for building help from markdown files, building updatable help files and generating file catalog. +- Updated build script with support for building help from markdown files, + building updatable help files and generating file catalog. - Initial release shows the basics of what this module could do. ## 0.2.0 - 2016-07-31 -- Introduced new directive `` that implicitlys expands the specified file(s), allowing the - template author to set the target file encoding. This new directive supports a wildcard source specifier - like the `` directive. With this change, `` no longer supports template expansion and as result - the `template` and `encoding` attributes have been removed. -- Restructured the module source to follow best practice of separating infrastructure from module files. -- Fixed #47: How to create empty directories. The `` directive supports this now. -- Fixed #58: File recurse does not work anymore. \ No newline at end of file +- Introduced new directive `` that implicitlys expands the + specified file(s), allowing the template author to set the target file + encoding. This new directive supports a wildcard source specifier like the + `` directive. With this change, `` no longer supports template + expansion and as result the `template` and `encoding` attributes have been + removed. +- Restructured the module source to follow best practice of separating + infrastructure from module files. +- Fixed #47: How to create empty directories. The `` directive supports + this now. +- Fixed #58: File recurse does not work anymore. diff --git a/Plaster/Plaster.psd1 b/Plaster/Plaster.psd1 index e0e5ce7..0f28db9 100644 --- a/Plaster/Plaster.psd1 +++ b/Plaster/Plaster.psd1 @@ -1,4 +1,4 @@ -@{ +@{ # Script module or binary module file associated with this manifest. RootModule = 'Plaster.psm1' diff --git a/Plaster/Templates/AddPSScriptAnalyzerSettings/plasterManifest.xml b/Plaster/Templates/AddPSScriptAnalyzerSettings/plasterManifest.xml index a07623f..9ae1eea 100644 --- a/Plaster/Templates/AddPSScriptAnalyzerSettings/plasterManifest.xml +++ b/Plaster/Templates/AddPSScriptAnalyzerSettings/plasterManifest.xml @@ -1,4 +1,4 @@ - + diff --git a/Plaster/Templates/NewPowerShellScriptModule/plasterManifest.xml b/Plaster/Templates/NewPowerShellScriptModule/plasterManifest.xml index 03c73a9..6c17104 100644 --- a/Plaster/Templates/NewPowerShellScriptModule/plasterManifest.xml +++ b/Plaster/Templates/NewPowerShellScriptModule/plasterManifest.xml @@ -1,4 +1,4 @@ - + diff --git a/cspell.json b/cspell.json index 800782d..24b9c81 100644 --- a/cspell.json +++ b/cspell.json @@ -16,7 +16,9 @@ "frommodule", "minimumversion", "plaster", + "multichoice", + "BHPS" ], "ignoreWords": [], "import": [] -} \ No newline at end of file +} diff --git a/examples/NewModule/editor/VSCode/tasks_pester.json b/examples/NewModule/editor/VSCode/tasks_pester.json index 6630bef..8e0fde2 100644 --- a/examples/NewModule/editor/VSCode/tasks_pester.json +++ b/examples/NewModule/editor/VSCode/tasks_pester.json @@ -49,5 +49,5 @@ }, "problemMatcher": [ "$pester" ] } - ] + ] } diff --git a/examples/NewModule/editor/VSCode/tasks_psake.json b/examples/NewModule/editor/VSCode/tasks_psake.json index 3d081b2..d58fce1 100644 --- a/examples/NewModule/editor/VSCode/tasks_psake.json +++ b/examples/NewModule/editor/VSCode/tasks_psake.json @@ -79,5 +79,5 @@ "command": "Invoke-psake build.psake.ps1 -taskList Publish", "problemMatcher": [] } - ] + ] } diff --git a/examples/NewModule/editor/VSCode/tasks_psake_pester.json b/examples/NewModule/editor/VSCode/tasks_psake_pester.json index 7ba6b0b..f413e48 100644 --- a/examples/NewModule/editor/VSCode/tasks_psake_pester.json +++ b/examples/NewModule/editor/VSCode/tasks_psake_pester.json @@ -89,5 +89,5 @@ }, "problemMatcher": [ "$pester" ] } - ] + ] } diff --git a/examples/TemplateModule/TemplateModule.psd1 b/examples/TemplateModule/TemplateModule.psd1 index 12ad1d4..673f023 100644 --- a/examples/TemplateModule/TemplateModule.psd1 +++ b/examples/TemplateModule/TemplateModule.psd1 @@ -1,4 +1,4 @@ -# +# # Module manifest for module 'TemplateModule' # diff --git a/examples/plasterManifest_fr-FR.xml b/examples/plasterManifest_fr-FR.xml index 2c71ac6..99eb34a 100644 --- a/examples/plasterManifest_fr-FR.xml +++ b/examples/plasterManifest_fr-FR.xml @@ -1,4 +1,4 @@ - +