From fdbc9a3a6dc2c68ca2b27b0efcb054e331e46bc0 Mon Sep 17 00:00:00 2001 From: Sam Erde <20478745+SamErde@users.noreply.github.com> Date: Tue, 2 Jun 2026 13:14:06 -0400 Subject: [PATCH] docs: consolidate Roadmap.md into Architecture and remove root roadmap Fold the forward-looking roadmap into docs/ and drop the standalone root file. Reviewed each roadmap item: - Already tracked/done (NOT re-added): the Microsoft.PowerShell.PlatyPS help migration (CHANGELOG [Unreleased]); "list installed modules with MSAL" (ships as Get-ModulesWithVersionSortedIdentityClient / Get-ModulesWithDependency); PowerShell 7.4+ compatibility and dependency/supply-chain hardening (ongoing, documented in Architecture sections 3 and 8 and Deep-Dive). - Truly new (added to Architecture section 9 "Known gaps / follow-ups" as a "Planned feature enhancements" backlog): import a specific MSAL version; verify package hash/signature vs source metadata; preload additional non-identity assemblies; preload-from-installed mode; import a named assembly set; clean up older installed DLLPickle versions. Repoint the README "Project Documentation Map" entry from the removed Roadmap.md to docs/Architecture.md (also adds the previously-missing Architecture blueprint link). The CHANGELOG's historical "README and Roadmap" release note is left intact. Co-Authored-By: Claude Opus 4.8 --- README.md | 2 +- Roadmap.md | 29 ----------------------------- docs/Architecture.md | 7 +++++++ 3 files changed, 8 insertions(+), 30 deletions(-) delete mode 100644 Roadmap.md diff --git a/README.md b/README.md index d4de172..cdac28c 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ All libraries tracked for pre-loading by DLL Pickle are maintained and documente - Deep technical explanation: [docs/Deep-Dive.md](docs/Deep-Dive.md) - Full command reference: [docs/DLLPickle.md](docs/DLLPickle.md) - Changelog and active work: [CHANGELOG.md](CHANGELOG.md) -- Planned work: [Roadmap.md](Roadmap.md) +- Architecture blueprint and planned enhancements: [docs/Architecture.md](docs/Architecture.md) - Contribution workflow: [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) - Dependency and supply chain policy: [DEPENDENCIES.md](DEPENDENCIES.md) - Security vulnerability reporting: [SECURITY.md](SECURITY.md) diff --git a/Roadmap.md b/Roadmap.md deleted file mode 100644 index a2112e3..0000000 --- a/Roadmap.md +++ /dev/null @@ -1,29 +0,0 @@ -# Roadmap - -This roadmap focuses on upcoming work. For released and in-progress engineering -details, see [CHANGELOG.md](CHANGELOG.md). - -## Active Work (Near Term) - -- Continue migration from legacy PlatyPS help generation to - `Microsoft.PowerShell.PlatyPS` workflow. -- Keep compatibility and reliability improvements for PowerShell 7.4+. -- Continue dependency lifecycle and supply chain hardening work. - -## Planned Enhancements - -- Add functions: - - import a specific version of MSAL. - - verify package hash/signature against original source metadata. -- Add option to preload other common assemblies -- Add an option to inspect and preload the newest version of relevant - assemblies only from those already included with installed modules on the - current system. -- Add function to import specific sets of assemblies. -- Add function to clean up older DLLPickle module versions. -- List all installed modules that include the MSAL - -## Notes - -- Items are not guaranteed in order. -- Large dependency or platform shifts may change implementation priority. diff --git a/docs/Architecture.md b/docs/Architecture.md index ece661a..aec029d 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -122,3 +122,10 @@ When changing the preload contract, follow this loop: - **EXO/Teams ALC ownership** is not yet captured — a bare `Import-Module` doesn't eager-load their identity assemblies; the probe needs a representative `-ProbeCommand`. - **Multi-TFM (net9.0/net10.0):** deferred; the methodology is TFM-parameterizable. net9.0/net10.0 are ALC-capable, so the `block` verdicts in §3 carry over to them. The `net8.0` bundle is confirmed to load on **PS 7.6 / .NET 10 via roll-forward** (Az.Resources import verified, no #193 regression) — a positive signal that multi-TFM is mostly a packaging exercise, not a behavioral one, on ALC-capable runtimes. - **Re-introducing Windows PowerShell 5.1 / net48 (no ALC) — checklist if attempted:** because net48 has no `AssemblyLoadContext`, modules cannot self-isolate and the §3 `block` verdicts for the Azure SDK stack **invert**. Re-support would require: (1) multi-targeting the build to `net48` alongside `net8.0`; (2) **conditionally preloading the Azure SDK stack** (`Azure.Core` + `Azure.Identity`/`Broker` + `System.ClientModel`) for net48 only — pinned to the highest version the WinPS-supported module set agrees on, as #183 did; (3) restoring net48-specific dependency conditions in `DLLPickle.csproj` (e.g. `Condition="'$(TargetFramework)' == 'net48'"`); (4) restoring `CompatiblePSEditions = @('Core','Desktop')` and lowering the manifest `PowerShellVersion`, plus per-edition guards in `Import-DPLibrary`; (5) adding WinPS 5.1 to the CI test matrix and re-validating the #156/#165-class scenarios. The 2.0 refactor's mistake was applying the net48-era Azure.Core preload to net8 unconditionally — any re-introduction must keep it **strictly TFM-conditional**. +- **Planned feature enhancements (backlog).** Forward-looking ideas consolidated from the former root `Roadmap.md`; not yet scheduled, order is not guaranteed, and large dependency/platform shifts may change priority. (Released and in-progress work lives in [CHANGELOG.md](../CHANGELOG.md) — for example the `Microsoft.PowerShell.PlatyPS` help-generation migration is already tracked there, and the broader PowerShell 7.4+ compatibility and supply-chain hardening work is the ongoing subject of §3 and §8.) + - Import a specific version of MSAL (`Microsoft.Identity.Client`) on demand, rather than only the bundled pin. + - Verify a package's hash/signature against the original source (e.g. NuGet) metadata before preload — a supply-chain integrity check extending the §8 dependency work. + - Option to preload additional common (non-identity) assemblies beyond the default identity stack. + - Option to inspect and preload only the newest version of relevant assemblies already present among the modules installed on the current system. The inspection side already exists (`Get-ModuleImportCandidate`, `Get-ModulesWithVersionSortedIdentityClient`, `Find-DLLInPSModulePath`); this would add the preload-from-installed mode. + - A function to import a specific named set of assemblies — a targeted alternative to the full `Import-DPLibrary` set or `Import-DPBaseProfile`. + - A function to clean up older installed DLLPickle module versions.