Merge pull request #15 from tablackburn/chore/template-changelog

Add template-level CHANGELOG.md (CalVer)

Author: tablackburn

CHANGELOG.md

@@ -1,15 +1,34 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this template will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+and this project uses [Calendar Versioning](https://calver.org/) (`YYYY.MM.DD`).
+
+For the changelog of a *module initialized from this template*, see the module's
+own `CHANGELOG.md` (generated from `CHANGELOG.template.md` during init).
 
 ## [Unreleased]
 
-## [0.1.0] - {{Date}}
+## [2026.04.29] - 2026-04-29
 
 ### Added
 
-- Initial release
-- `Get-{{Prefix}}Example` - Example public function
+- SemVer-aware dependency version checks: new `tests/ManifestHelpers.psm1` exporting `Test-VersionConstraint`. `tests/Manifest.tests.ps1` now differentiates `RequiredVersion` / `ModuleVersion` / `MaximumVersion`, accepts both string and hashtable shapes in `requirements.psd1`, and detects duplicate `RequiredModules` entries.
+- README split: template-facing `README.md` (what GitHub visitors see) and module-facing `README.template.md` (substituted into `README.md` during init).
+- `docs/en-US/about_{{ModuleName}}.help.md` stub for `Get-Help about_<Module>`. `Initialize-Template.ps1` now also renames `{{ModuleName}}` files in `docs/en-US/`.
+- `.gitattributes` marking `docs/en-US/*` as `linguist-generated`.
+- `.markdownlint-cli2.jsonc` config (relax MD013 in tables/code, allow MD024 siblings, ignore generated docs and `instructions/`).
+
+### Changed
+
+- `PSScriptAnalyzerSettings.psd1`: replaced one-line `@{ IncludeRules = @('*') }` with the structured form (Include/Exclude/Rules + commented compat scaffold).
+- Bumped `PSScriptAnalyzer` 1.24.0 → 1.25.0.
+
+### Fixed
+
+- `tests/Help.tests.ps1`: replaced undefined `$parameterNames` with `$commandParameterNames` in the help-vs-code parameter check (was silently asserting against `$null`).
+- `{{ModuleName}}/{{ModuleName}}.psm1`: dot-source catch block now preserves the original `ErrorRecord` via bare `throw`. Previously the catch threw a new string (`"Unable to dot source ..."`), which wrapped the original exception in a fresh `ErrorRecord` and lost the underlying stack trace.
+
+[Unreleased]: https://github.com/tablackburn/PowerShellModuleTemplate/compare/v2026.04.29...HEAD
+[2026.04.29]: https://github.com/tablackburn/PowerShellModuleTemplate/releases/tag/v2026.04.29

CHANGELOG.template.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - {{Date}}
+
+### Added
+
+- Initial release
+- `Get-{{Prefix}}Example` - Example public function

Initialize-Template.ps1

@@ -180,6 +180,7 @@ $filesToProcess = Get-ChildItem -Path $PSScriptRoot -Recurse -File | Where-Objec
     $_.FullName -notmatch '[\\/]Output[\\/]' -and
     $_.FullName -notmatch '[\\/]out[\\/]' -and
     $_.Name -ne 'Initialize-Template.ps1' -and
+    $_.Name -ne 'CHANGELOG.md' -and
     $_.Extension -in @('.ps1', '.psm1', '.psd1', '.md', '.json', '.yml', '.yaml', '.xml', '.txt', '')
 }
 
@@ -287,6 +288,15 @@ if (Test-Path -Path $readmeTemplate) {
     Write-Host '  Generated module README.md from template' -ForegroundColor Green
 }
 
+# Replace template-facing CHANGELOG.md with the module-facing CHANGELOG.template.md
+# (placeholders inside CHANGELOG.template.md were already substituted by the file-processing loop above)
+$changelogTemplate = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.template.md'
+$changelogPath = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.md'
+if (Test-Path -Path $changelogTemplate) {
+    Move-Item -Path $changelogTemplate -Destination $changelogPath -Force
+    Write-Host '  Generated module CHANGELOG.md from template' -ForegroundColor Green
+}
+
 # Initialize Git repository if requested
 if (-not $NoGitInit) {
     $gitFolder = Join-Path -Path $PSScriptRoot -ChildPath '.git'

README.md

@@ -117,6 +117,10 @@ The test suite runs against the `{{ModuleName}}` placeholder module to verify th
 - Git
 - (Optional) Docker for the devcontainer
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the template's version history. The template uses [Calendar Versioning](https://calver.org/) (`YYYY.MM.DD`) — the version reflects when a snapshot of the template was cut, not API compatibility.
+
 ## License
 
 [MIT](LICENSE)

tests/Manifest.tests.ps1

@@ -86,6 +86,14 @@ BeforeDiscovery {
     }
     $manifestData = Test-ModuleManifest @testModuleManifestParameters
     $dependencies = $manifestData.RequiredModules
+
+    # When running on the un-initialized template, CHANGELOG.md tracks the template's
+    # CalVer version (YYYY.MM.DD), which deliberately decouples from the manifest's
+    # ModuleVersion. Skip the equality assertion in that case; downstream modules (post-init)
+    # keep the assertion. Marker: CHANGELOG.template.md exists only pre-init —
+    # Initialize-Template.ps1 moves it onto CHANGELOG.md during init. The marker survives
+    # the init substitution loop because no token in the path matches a {{Placeholder}}.
+    $isTemplate = Test-Path -LiteralPath (Join-Path -Path $Env:BHProjectPath -ChildPath 'CHANGELOG.template.md')
 }
 BeforeAll {
     # Check if the BHBuildOutput environment variable exists to determine if this test is running in a psake
@@ -180,7 +188,7 @@ Describe 'Module manifest' {
             $changelogVersion -as [Version] | Should -Not -BeNullOrEmpty
         }
 
-        It 'Changelog and manifest versions are the same' {
+        It 'Changelog and manifest versions are the same' -Skip:$isTemplate {
             $changelogVersion -as [Version] | Should -Be ( $manifestData.Version -as [Version] )
         }