From 4d5ebd75728146cd672ab8f8e224e57c51fed110 Mon Sep 17 00:00:00 2001 From: TheSevenPens <98374109+TheSevenPens@users.noreply.github.com> Date: Sat, 9 May 2026 16:42:56 -0700 Subject: [PATCH] release(psmodule): finish Visio.psd1 deprecation cleanup (closes #178) Three one-line edits in Visio.psd1: 1. ModuleToProcess = 'VisioPS.dll' -> RootModule = 'VisioPS.dll'. The deprecated ModuleToProcess member was emitting Publish-Module warnings on every PSGallery upload ('The module manifest member ModuleToProcess has been deprecated. Use the RootModule member instead.', fired twice per publish). The historical comment about needing ModuleToProcess for PS 2.0/3.0 compatibility is moot: the binary cmdlets are compiled against Microsoft.PowerShell.3.ReferenceAssemblies and never loadable on PS 2.0 regardless of what the manifest claimed. 2. PowerShellVersion = '2.0' -> '5.1'. Aligns the manifest with what the module actually requires. PSGallery's Install-Module gates at PS 5.1; the local Publish-VisioPSToGallery.ps1 also refuses to run below 5.1; LTSB 2016 ships PS 5.1; the binary cmdlets need PS 3.0 minimum. 3. CLRVersion = '4.0' removed (set to commented-out placeholder). PS 5.1 already implies CLR 4.0+; the shipping libs target .NET Framework 4.5.2, not 4.0; the declaration was inaccurate even when present. Customer impact: zero. The current PowerShellVersion = '2.0' was aspirational, not real. Bumping aligns the declaration with what the module already requires; no extant user becomes unable to run it. Verified: - Import-PowerShellDataFile parses cleanly (RootModule=VisioPS.dll, PowerShellVersion=5.1, CLRVersion not set, ModuleVersion=4.7.2, CmdletCount=64). - Solution builds clean. - All 20 VTest.PowerShell tests pass (which exercise the manifest via runspace-based test infrastructure including Manifest_CmdletsToExport_HasNoMissingEntries / HasNoExtraEntries). CHANGELOG[Unreleased] gets a "Changed" entry. The futures/releases.md 'Address Visio.psd1 deprecation warnings' entry moves to COMPLETED.md under Phase 3 Build & tooling per the futures->COMPLETED convention. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../VisioPowerShell/CHANGELOG.md | 1 + .../VisioPowerShell/Visio.psd1 | 7 ++-- docs/COMPLETED.md | 4 +++ docs/futures/releases.md | 33 ------------------- 4 files changed, 8 insertions(+), 37 deletions(-) diff --git a/VisioAutomation_2010/VisioPowerShell/CHANGELOG.md b/VisioAutomation_2010/VisioPowerShell/CHANGELOG.md index f0eb9327d..653a4bff7 100644 --- a/VisioAutomation_2010/VisioPowerShell/CHANGELOG.md +++ b/VisioAutomation_2010/VisioPowerShell/CHANGELOG.md @@ -15,6 +15,7 @@ The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/ ### Changed - Module manifest's `Author` and `Copyright` fields updated from `Saveen Reddy` to `SevenPens` to reflect the new dev-team identity. No functional change; the displayed-author string on the [PSGallery package page](https://www.powershellgallery.com/packages/Visio) updates on the next release. Legal copyright record (LICENSE.txt) updated correspondingly. - Module is now built and published as **Release** instead of Debug. The published `.zip` and PSGallery package contain optimized binaries with no `[Debuggable]` attribute and no `.pdb` symbol files. No source-level behavior change (the C# source has no `#if DEBUG` blocks) but assemblies are smaller and JIT optimizations are no longer suppressed. Closes [#177](https://github.com/saveenr/VisioAutomation/issues/177). +- Module manifest cleanup: `ModuleToProcess = 'VisioPS.dll'` switched to `RootModule = 'VisioPS.dll'` (the deprecated `ModuleToProcess` member was emitting `Publish-Module` warnings on every PSGallery upload), and `PowerShellVersion = '2.0'` bumped to `'5.1'` to match what the binary cmdlets actually require (compiled against `Microsoft.PowerShell.3.ReferenceAssemblies`, never loadable on PS < 3.0; PSGallery and `Publish-VisioPSToGallery.ps1` already gate at PS 5.1). Removed the now-vestigial `CLRVersion = '4.0'` declaration; the shipping libs target .NET Framework 4.5.2 and PS 5.1 already implies CLR 4.0+. **Customer impact: zero** — aligns the manifest's declarations with what the module actually requires; no extant user becomes unable to run it. Closes [#178](https://github.com/saveenr/VisioAutomation/issues/178). ## [4.7.2] - 2026-05-06 diff --git a/VisioAutomation_2010/VisioPowerShell/Visio.psd1 b/VisioAutomation_2010/VisioPowerShell/Visio.psd1 index 7f10f75fe..633633cc3 100644 --- a/VisioAutomation_2010/VisioPowerShell/Visio.psd1 +++ b/VisioAutomation_2010/VisioPowerShell/Visio.psd1 @@ -4,8 +4,7 @@ @{ # Script module or binary module file associated with this manifest. -# RootModule = 'VisioPS.dll' - Commented this out because having RootModule defined causes the module to fail to load with PowerShell 2.0 -ModuleToProcess = 'VisioPS.dll' # Use ModuleToProcess instead of RootModule because it works for both PowerShell 2.0 and 3.0 +RootModule = 'VisioPS.dll' # Version number of this module. ModuleVersion = '4.7.2' @@ -26,7 +25,7 @@ Copyright = 'SevenPens' Description = 'Visio PowerShell - Automation cmdlets for Visio version 2010 and above' # Minimum version of the Windows PowerShell engine required by this module -PowerShellVersion = '2.0' +PowerShellVersion = '5.1' # Name of the Windows PowerShell host required by this module # PowerShellHostName = '' @@ -38,7 +37,7 @@ PowerShellVersion = '2.0' # DotNetFrameworkVersion = '' # Minimum version of the common language runtime (CLR) required by this module -CLRVersion = '4.0' +# CLRVersion = '' # Processor architecture (None, X86, Amd64) required by this module # ProcessorArchitecture = '' diff --git a/docs/COMPLETED.md b/docs/COMPLETED.md index 80b388fd7..58994c471 100644 --- a/docs/COMPLETED.md +++ b/docs/COMPLETED.md @@ -83,6 +83,10 @@ Headline summary in [`ROADMAP.md`](ROADMAP.md#phase-3--modernization-in-progress - **What:** PSGallery publish was a manual local-machine flow via [`Publish-VisioPSToGallery.ps1`](../VisioAutomation_2010/VisioPowerShell/Publish-VisioPSToGallery.ps1) with the API key on the developer's workstation. Goal: shift to a CI publish that takes the GitHub Release artifact (already produced by [`release-psmodule.yml`](../.github/workflows/release-psmodule.yml)) and uploads it to PSGallery, so the binary on PSGallery is exactly the one humans inspected on the GH Release, and the API key lives only as a GitHub Actions secret. Stated more concretely as a futures item after the manual 4.7.0 publish surfaced the local-machine friction (Smart App Control transient blocks, "use a fresh PowerShell session" caveat, API-key-on-workstation footprint). - **Resolution:** New [`.github/workflows/publish-psmodule.yml`](../.github/workflows/publish-psmodule.yml). `workflow_dispatch`-triggered, takes the release tag as input, downloads the `Visio-.zip` artifact from the GH Release via `gh release download`, extracts it, verifies the staged `ModuleVersion` matches the tag, runs a `CmdletsToExport` drift check (loads the module and compares declared cmdlets vs the binary's `ExportedCmdlets`), forces TLS 1.2, runs `Publish-Module`, then verifies the upload via `Find-Module` with retry. Has a `dry_run` input that exercises every step except the actual upload — lets the workflow be tested against the existing 4.7.0 GH Release without touching PSGallery, since gallery versions are immutable. Companion change: `Publish-VisioPSToGallery.ps1`'s tag step refactored to be idempotent (skips silently if the tag already exists at HEAD; throws if the tag exists but points elsewhere) so the local script and the workflow can coexist for fallback / out-of-band publishes. The `CmdletsToExport='*'` → explicit-list change in `bd627062` is the prereq that made the drift check possible. Setup required: `PSGALLERY_API_KEY` repository secret (one-time, mentioned in the workflow file's header comment). +#### Address `Visio.psd1` deprecation warnings on PSGallery publish +- **What:** Two final pieces of the long-running [`Visio.psd1`](../VisioAutomation_2010/VisioPowerShell/Visio.psd1) cleanup that started 2026-05. The `CmdletsToExport` half had landed earlier (manifest now lists 64 cmdlets explicitly so the publish-time best-practice warning is silent). Still pending: the `ModuleToProcess` → `RootModule` rename and the `PowerShellVersion` bump. Each 4.7.x publish to PSGallery had been emitting `The module manifest member 'ModuleToProcess' has been deprecated. Use the 'RootModule' member instead.` (twice per upload). +- **Resolution (closes [#178](https://github.com/saveenr/VisioAutomation/issues/178)):** Three one-line edits in [`Visio.psd1`](../VisioAutomation_2010/VisioPowerShell/Visio.psd1): (1) `ModuleToProcess = 'VisioPS.dll'` → `RootModule = 'VisioPS.dll'` (the historical comment about needing `ModuleToProcess` for PS 2.0 / 3.0 compat is moot; the binary cmdlets are compiled against `Microsoft.PowerShell.3.ReferenceAssemblies` and have never been loadable on PS 2.0); (2) `PowerShellVersion = '2.0'` → `'5.1'` to match what PSGallery's `Install-Module` and the local `Publish-VisioPSToGallery.ps1` already require; (3) the now-vestigial `CLRVersion = '4.0'` declaration removed (PS 5.1 already implies CLR 4.0+; the shipping libs target .NET Framework 4.5.2, not 4.0). **Customer impact: zero** — the bumped declarations align with what the module actually requires; no extant user becomes unable to run it (PS 5.1 is the de facto floor today via Windows 10 1607+ / LTSB 2016 / Win 11 / Server 2016+; pre-5.1 installs were already blocked by the binary cmdlets and the publish path). + ### Code & architecture #### PowerShell cmdlet positional-parameter UX audit diff --git a/docs/futures/releases.md b/docs/futures/releases.md index 008448f87..311f8bfaf 100644 --- a/docs/futures/releases.md +++ b/docs/futures/releases.md @@ -22,39 +22,6 @@ Backlog of items related to release process, version policy, and publishing to p - **Cross-refs:** *Automate releases via GitHub CI* below — the CI workflow either flips the constant or stages the release config separately. - **Effort:** S. -### Address `Visio.psd1` deprecation warnings on PSGallery publish -- **Status (2026-05-06):** the `CmdletsToExport` half landed (manifest now lists 64 cmdlets explicitly; the publish-time best-practice warning will be silent on the next release). The `ModuleToProcess` → `RootModule` rename and `PowerShellVersion` bump are still pending; deferred deliberately, not blocked. Customer-impact analysis below. -- **What's left:** The 4.7.0 publish to PSGallery (2026-05-06) emitted these still-active warnings from `Publish-Module`: - - `The module manifest member 'ModuleToProcess' has been deprecated. Use the 'RootModule' member instead.` (fires twice — once during local staging, once on the gallery upload). -- **Why the warning fires:** [`Visio.psd1`](../../VisioAutomation_2010/VisioPowerShell/Visio.psd1) line 8 sets `ModuleToProcess = 'VisioPS.dll'` with an inline comment ("Use ModuleToProcess instead of RootModule because it works for both PowerShell 2.0 and 3.0") and the manifest declares `PowerShellVersion = '2.0'`. The compatibility target is essentially dead: PS 2.0 was removed from Windows 11; PSGallery's `Install-Module` requires PS 5.1+; [`Publish-VisioPSToGallery.ps1`](../../VisioAutomation_2010/VisioPowerShell/Publish-VisioPSToGallery.ps1) itself refuses to run below PS 5.1. -- **How to apply when picked up:** - - Switch `ModuleToProcess` to `RootModule` in [`Visio.psd1`](../../VisioAutomation_2010/VisioPowerShell/Visio.psd1) (toggle the comment on lines 7-8). Bump `PowerShellVersion = '2.0'` to `'5.1'` to match the publish script's own minimum check. Optionally drop `CLRVersion = '4.0'` (paired with .NET Framework 4.0; the shipping libs target 4.5.2). - -#### Customer impact of the `PowerShellVersion = '2.0'` → `'5.1'` bump - -(Pre-derived 2026-05-06 so it doesn't have to be reasoned through again when this is picked up.) - -| PS version | Ships with | Status | Impact of bump | -|---|---|---|---| -| 7.x | separate install, cross-platform | current | unaffected (7 satisfies the `>= 5.1` floor) | -| 5.1 | Windows 10 1607+ (2016), Win 11, Server 2016+ | current | **unaffected** — this is the de facto floor today | -| 5.0 | Windows 10 1507/1511 only (2015-2016) | unsupported Windows | newly blocked, but Windows itself is end-of-life | -| 4.0 | Windows 8.1, Server 2012 R2 | OOS since 2023 | newly blocked, but unlikely to be a VisioPS user | -| 3.0 | Windows 8 | OOS since 2023 | same | -| 2.0 | Windows 7 | OOS since 2020 | already broken — the binary cmdlets are compiled against `Microsoft.PowerShell.3.ReferenceAssemblies` and won't load on PS 2.0 regardless of what the manifest claims | - -Effective customer impact: **zero**. The current `PowerShellVersion = '2.0'` is aspirational, not real; the binary already won't run on anything below PS 3.0, and the entire installation path (PSGallery + `Publish-VisioPSToGallery.ps1`) gates at 5.1. Bumping the manifest aligns the declaration with what the module actually requires; no extant user becomes unable to run it. LTSB 2016 (the ongoing compat constraint until 2026-10-13) ships with PS 5.1, so the bump does not affect those users either. - -#### Maintenance note on `CmdletsToExport` -The list now has 64 entries. Adding a new cmdlet requires also adding it to the manifest. Two options to enforce when convenient: -- (a) Manual reminder in cmdlet-author docs / `CONTRIBUTING.md`. -- (b) Pre-publish check that loads the staged module, diffs `Get-Module -Name Visio | Select-Object -ExpandProperty ExportedCmdlets` against the manifest's `CmdletsToExport`, and fails if they differ. Drop into `Publish-VisioPSToGallery.ps1` between the staging step and the `Publish-Module` call. - -Option (b) is a few lines of PowerShell; worth adding when the *PSGallery publish via "release first..."* item below lands, since that's the natural place to put the check. - -- **Cross-refs:** *Automate releases via GitHub CI* below — the publish workflow should also surface these warnings as a CI signal so future drift is caught early. -- **Effort to finish:** S. Single commit, no behavior change for any extant user. The `RootModule` swap is one line; the `PowerShellVersion` bump is one line. - ### Automate releases via GitHub CI *(in progress)* - **What:** Replace the current manual release process with GitHub Actions workflows that handle **three deliverables** end-to-end: 1. **PSGallery publish** of the `Visio` PowerShell module — ✅ landed, see below.