From 605409c0ca447db601b228ae6a391c55de42daf7 Mon Sep 17 00:00:00 2001 From: Sam Erde <20478745+SamErde@users.noreply.github.com> Date: Tue, 2 Jun 2026 13:33:39 -0400 Subject: [PATCH 1/2] docs: slim the README and refresh the first-level /docs files Make the README a fast on-ramp for new users and push reference/policy detail into /docs, plus fix accuracy/currency gaps found while reviewing the docs. README (171 -> 81 lines): - Merge the two duplicate "Using" blocks into one. - Condense the FAQ + "Example Scenario" narrative into a short "How It Works" that links to the Deep Dive (the full story already lives in docs/index.md and Deep-Dive.md). - Complete the command list: it previously listed only 7 of 9 exported commands (missing Import-DPBaseProfile and Test-DPLibraryConflict); now all 9, grouped Primary vs Inspection helpers. - Add Troubleshooting.md to the documentation map. Moved out of the README: - Versioning policy -> DEPENDENCIES.md, reconciled with reality: the old text described 4 segments (2.x.x.x) and an "MSAL update -> minor / refactor -> build" rule, but releases are 3-segment SemVer driven by Conventional Commits (feat->minor, fix->patch) and publish only on bundle changes. - Tracked-library NuGet documentation links -> DEPENDENCIES.md. - "Related GitHub Issues" list -> docs/Deep-Dive.md as motivating background. Docs accuracy/currency fixes (from the review): - docs/Troubleshooting.md: refresh the #174 section to the runtime-confirmed both-import-orders-fail conclusion, reference Test-DPLibraryConflict (2.2.0), and correct Az.Storage 9.6.0 -> 9.6.1. - docs/DLLPickle.md: add the missing Import-DPBaseProfile (linked) and Test-DPLibraryConflict (unlinked; per-command help page is generated by the in-progress Microsoft.PowerShell.PlatyPS migration) entries. index.md, Deep-Dive.md, and Architecture.md were reviewed and are current; the DLLPickle.md front-matter version/date will refresh on PlatyPS regeneration. Co-Authored-By: Claude Opus 4.8 --- DEPENDENCIES.md | 31 +++++ README.md | 251 +++++++++++++--------------------------- docs/DLLPickle.md | 8 ++ docs/Deep-Dive.md | 13 +++ docs/Troubleshooting.md | 26 +++-- 5 files changed, 150 insertions(+), 179 deletions(-) diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md index c1397251..957b2e9b 100644 --- a/DEPENDENCIES.md +++ b/DEPENDENCIES.md @@ -27,6 +27,24 @@ For usage guidance, see [README.md](README.md) and [docs/index.md](docs/index.md | **Major** (X.y.z) | Manual review | Explicit maintainer approval | | **Upstream PowerShell module drift** | Candidate PR or issue | Upstream Compatibility workflow | +## Versioning + +DLLPickle follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). +Releases are cut automatically by the **Release-and-Publish** workflow, which +derives the bump from [Conventional Commits](https://www.conventionalcommits.org/) +since the last tag: + +| Bump | Trigger | +| ---- | ------- | +| **MAJOR** (`X.y.z`) | A breaking change (a `!` / `BREAKING CHANGE` commit), or a bundled MSAL **major** version increment. | +| **MINOR** (`x.Y.z`) | A new feature (`feat:`), or a new / updated bundled dependency โ€” including the automated MSAL and identity-library version bumps that are the module's core purpose. | +| **PATCH** (`x.y.Z`) | Fixes (`fix:`), refactors, performance/logging tweaks, and other non-breaking corrections. | + +A new PowerShell Gallery version is published **only** when a change affects the +published module bundle (`src/DLLPickle/**` or the bundled package set). CI-, +docs-, policy-, and tooling-only changes do not trigger a release. See +[CHANGELOG.md](CHANGELOG.md) for the released history. + ## Upstream Compatibility Automation Dependabot tracks NuGet package releases, but DLLPickle also tracks the DLLs @@ -59,6 +77,19 @@ candidate generation, restore, build, and issue reproduction tests pass. | `Microsoft.IdentityModel.Tokens` | `8.*` | Token validation/processing | | `System.IdentityModel.Tokens.Jwt` | `8.*` | JWT handlers | +### Upstream package documentation + +The libraries DLLPickle tracks for preloading are maintained and documented by +their own code owners: + +- [Microsoft.Identity.Abstractions](https://www.nuget.org/packages/Microsoft.Identity.Abstractions) +- [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) +- [Microsoft.IdentityModel.Abstractions](https://www.nuget.org/packages/Microsoft.IdentityModel.Abstractions) +- [Microsoft.IdentityModel.JsonWebTokens](https://www.nuget.org/packages/Microsoft.IdentityModel.JsonWebTokens) +- [Microsoft.IdentityModel.Logging](https://www.nuget.org/packages/Microsoft.IdentityModel.Logging) +- [Microsoft.IdentityModel.Tokens](https://www.nuget.org/packages/Microsoft.IdentityModel.Tokens) +- [System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt) + ## Exact Pin Rationale - Exact pins are used for the MSAL managed family (`Microsoft.Identity.Client` diff --git a/README.md b/README.md index cdac28cf..459152ae 100644 --- a/README.md +++ b/README.md @@ -1,170 +1,81 @@ - -# ๐Ÿฅ’ DLL Pickle - -A PowerShell module that helps you get un-stuck from dependency version conflicts that can occur when connecting to multiple Microsoft online services. - - -![GitHub top language](https://img.shields.io/github/languages/top/SamErde/DLLPickle) -[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ae92f0d929de494690e712b68fb3b52c)](https://app.codacy.com/gh/SamErde/DLLPickle/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) -[![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/DLLPickle?include_prereleases)](https://powershellgallery.com/packages/DLLPickle) -[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11450/badge)](https://www.bestpractices.dev/projects/11450) - - -A stressed pickle trying to explain the problem in their code to a rubber duck. - -## ๐Ÿง‘โ€๐Ÿ’ป Getting Started - -### Prerequisites - -PowerShell 7.4 or later on Linux, macOS, or Windows. - -### Installation - -```powershell -Install-Module DLLPickle -Scope CurrentUser -``` - -Or, if you use **Microsoft.PowerShell.PSResourceGet**, run: - -```powershell -Install-PSResource -Name DLLPickle -``` - -### Using - -Import the module, then run `Import-DPLibrary` before connecting to service modules. - -```powershell -Import-Module DLLPickle -Import-DPLibrary -``` - -### Core Commands - -DLLPickle currently exports the following commands: - -- `Import-DPLibrary`: preload DLLPickle-managed assemblies in dependency-aware order. -- `Get-DPConfig`: view your current DLLPickle configuration. -- `Set-DPConfig`: update DLLPickle configuration (for example, show logo, skip libraries). -- `Find-DLLInPSModulePath`: inspect module paths for matching DLLs. -- `Get-ModuleImportCandidate`: determine which installed module version would import. -- `Get-ModulesWithDependency`: list installed modules that package a target dependency. -- `Get-ModulesWithVersionSortedIdentityClient`: compare modules by packaged `Microsoft.Identity.Client.dll` version. - -For complete syntax and examples, see: - -- [docs index](docs/index.md) -- [module command reference](docs/DLLPickle.md) - ---- - -## ๐Ÿ“ Description - -Let's start with a few FAQs: - -- **What does DLL Pickle actually *do*?** - - DLL Pickle pre-loads the newest version of the MSAL DLLs (and some of their transitive dependencies) that may be required by your other installed modules' and scripts' `Connect-*` cmdlets. (See the example below.) - -- **Why does it need to do this?** - - It is common for PowerShell modules to ship with DLLs that provide precompiled functionality or dependencies. A PowerShell session cannot import two different versions of the same library (DLL). If a module imports one version of a DLL and then a different module attempts to import a second, newer version of that DLL, they will typically see an error that says, "an assembly with the same name is already loaded" and the second module will not be able to function. - -- **Why don't modules use Application Load Context (ALC) to solve this problem?** - - ALC can be very complex to implement *and* is only available in PowerShell 7. For these reasons, it is not commonly used in public modules. - -- **Do these issues look familiar?** - -### Related GitHub Issues - -- [Connect-MgGraph fails after Connect-ExchangeOnline](https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/3394) -- [UUF Customer feedback: Get-EntraExtensionProperty error](https://github.com/microsoftgraph/entra-powershell/issues/1258) (Assembly with same name is already loaded) -- [Assembly with same name is already loaded](https://github.com/microsoftgraph/entra-powershell/issues/1083) -- [Design entra-powershell with ALC bridge pattern for a more robust assembly load handling](https://github.com/microsoftgraph/entra-powershell/issues/1242) -- [Implement proper assembly isolation to play nice with vscode-powershell](https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/2978) -- [Conflict with the .Net dll of the Az module PowerShell/vscode-powershell#3012](https://github.com/PowerShell/vscode-powershell/issues/3012) -- [Unable to load Az modules - Assembly with same name is already loaded PowerShell/vscode-powershell#4727](https://github.com/PowerShell/vscode-powershell/issues/4727) - -### ๐Ÿง‘โ€๐Ÿ’ป An Example Scenario - -Numerous PowerShell modules include a dependency on the Microsoft Authentication Library (MSAL) for authenticating to Microsoft's online services. The latest version of the MSAL is actively maintained in **[AzureAD/microsoft-authentication-library-for-dotnet](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet)**. However, modules that depend on the MSAL libraries (such as **Microsoft.Identity.Client.dll**) all update their releases with different versions of MSAL on different schedules. This results in version conflicts that break authentication flows whenever you try to use multiple modules in one session. Examples of modules that can be affected by this include: - -- Az.Accounts -- ExchangeOnlineManagement -- Microsoft.Graph.Authentication -- MicrosoftTeams -- ...and many more. - -You could *manually* attempt to work around this by checking which version of the conflicting DLLs are used by each of your PowerShell modules and then *connect first* to whichever service module uses the newest version of the DLL. This works because of the "first one wins" rule and because the MSAL is designed to be backwards compatible. DLL Pickle handles this for you by automatically updating and releasing a new version of DLL Pickle whenever a new version of the MSAL is published. As long as you keep the DLL Pickle module up to date and run `Import-DPLibrary` before other modules, you should be able to connect to any Microsoft online service without DLL conflicts. - -### ๐Ÿฅ’ Using DLL Pickle - -The easiest way to benefit from DLL Pickle is to import the module in your PowerShell profile before any other module or assembly is loaded. Just add the line `Import-DPLibrary` to your profile, save it, and start a new instance of PowerShell. - -Alternatively, if you are starting work in a new PowerShell session in which you know you will be authenticating to multiple online services, you can run `Import-DPLibrary` at the beginning of your session and then proceed with connecting to Microsoft's online services using their first party modules. - -### โš™๏ธ Platform Support - -- **PowerShell 7.4+ (Core, net8.0):** Fully supported target runtime. - -If you need diagnostic details, run: - -```powershell -Import-DPLibrary -ShowLoaderExceptions -Verbose -``` - -For detailed cmdlet guidance, see [docs/DLLPickle/Import-DPLibrary.md](docs/DLLPickle/Import-DPLibrary.md). - -For deeper compatibility and dependency details, see [DEPENDENCIES.md](DEPENDENCIES.md). - ---- - -## ๐Ÿ“ Additional Information - -### Versioning - -This project follows the semantic versioning model. It also packages numerous dependencies that follow their own versioning. To maintain clarity, this project will follow SemVer standards and the following logic for version changes: - -#### Major Versions - -๐Ÿท๏ธ **2.x.x.x** - The major version will only change if there is a breaking change in the DLL Pickle project or if an MSAL dependency is released with a new major version (potentially indicating a breaking change). - -#### Minor Versions - -๐Ÿท๏ธ **X.1.X.X** - The minor version will change if any of the following occur: - -- New features are added to the project -- New MSAL library dependencies are added to the project -- A new version of any associated library (DLL) is automatically updated within the project - -#### Build Versions - -๐Ÿท๏ธ **X.X.1.X** - The build version will change if any of the following occur: - -- Minor refactoring for performance, error handling, or logging -- Minor fixes for typos or formatting - -## External Documentation - -All libraries tracked for pre-loading by DLL Pickle are maintained and documented by their own code owners. Please see each project accordingly: - -- [Microsoft.Identity.Abstractions](https://www.nuget.org/packages/Microsoft.Identity.Abstractions) -- [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) -- [Microsoft.IdentityModel.Abstractions](https://www.nuget.org/packages/Microsoft.IdentityModel.Abstractions) -- [Microsoft.IdentityModel.JsonWebTokens](https://www.nuget.org/packages/Microsoft.IdentityModel.JsonWebTokens) -- [Microsoft.IdentityModel.Logging](https://www.nuget.org/packages/Microsoft.IdentityModel.Logging) -- [Microsoft.IdentityModel.Tokens](https://www.nuget.org/packages/Microsoft.IdentityModel.Tokens) -- [System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt) - -## Project Documentation Map - -- User guide and overview: [docs/index.md](docs/index.md) -- 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) -- 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) + +# ๐Ÿฅ’ DLL Pickle + +A PowerShell module that helps you get un-stuck from dependency version conflicts that can occur when connecting to multiple Microsoft online services. + + +![GitHub top language](https://img.shields.io/github/languages/top/SamErde/DLLPickle) +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ae92f0d929de494690e712b68fb3b52c)](https://app.codacy.com/gh/SamErde/DLLPickle/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) +[![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/DLLPickle?include_prereleases)](https://powershellgallery.com/packages/DLLPickle) +[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11450/badge)](https://www.bestpractices.dev/projects/11450) + + +A stressed pickle trying to explain the problem in their code to a rubber duck. + +## ๐Ÿง‘โ€๐Ÿ’ป Getting Started + +### Prerequisites + +PowerShell 7.4 or later on Linux, macOS, or Windows. + +### Installation + +```powershell +Install-Module DLLPickle -Scope CurrentUser +``` + +Or, with **Microsoft.PowerShell.PSResourceGet**: + +```powershell +Install-PSResource -Name DLLPickle +``` + +### Using + +Import DLL Pickle and run `Import-DPLibrary` **before** connecting to other service modules โ€” ideally as the first thing in your PowerShell profile, so it loads first in every session. + +```powershell +Import-Module DLLPickle +Import-DPLibrary +``` + +For diagnostic detail, add `-ShowLoaderExceptions -Verbose`. + +### Commands + +**Primary:** + +- `Import-DPLibrary` โ€” preload DLLPickle-managed assemblies in dependency-aware order. +- `Import-DPBaseProfile` โ€” preload, then import the validated base-profile modules (Exchange Online, Teams, Graph, Az.Accounts) in a known-good order. +- `Test-DPLibraryConflict` โ€” report known-incompatible module pairs loaded in the current session, with the workaround. +- `Get-DPConfig` / `Set-DPConfig` โ€” view or change configuration (for example, show logo, skip libraries). + +**Inspection helpers:** + +- `Find-DLLInPSModulePath` โ€” find DLLs across module paths, filtered by product metadata. +- `Get-ModuleImportCandidate` โ€” show which installed module version would import. +- `Get-ModulesWithDependency` โ€” list installed modules that package a given dependency. +- `Get-ModulesWithVersionSortedIdentityClient` โ€” compare modules by packaged `Microsoft.Identity.Client.dll` version. + +Full syntax and examples: [docs index](docs/index.md) ยท [command reference](docs/DLLPickle.md). + +## ๐Ÿฅ’ How It Works + +Many PowerShell modules โ€” Az, Exchange Online, Microsoft Graph, Teams, and more โ€” bundle their own copy of the Microsoft Authentication Library (MSAL) and related DLLs. A single PowerShell session can only load **one** version of a given DLL, so when two modules ship different versions you hit *"an assembly with the same name is already loaded"* and authentication breaks. + +DLL Pickle preloads a current, compatible set of these assemblies **first**, so the "first one wins" rule works in your favor and the modules you load afterward reuse what's already there. A new DLL Pickle release is published automatically whenever a new MSAL version ships โ€” so keep it updated and load it first. + +For the full explanation (and the real-world issues that motivated it), read the [Deep Dive](docs/Deep-Dive.md). The supported platform is **PowerShell 7.4+ (Core, net8.0)**; compatibility, versioning, and dependency details live in [DEPENDENCIES.md](DEPENDENCIES.md). + +## ๐Ÿ“š Documentation Map + +- User guide and overview: [docs/index.md](docs/index.md) +- Deep technical explanation: [docs/Deep-Dive.md](docs/Deep-Dive.md) +- Troubleshooting and issue reproduction: [docs/Troubleshooting.md](docs/Troubleshooting.md) +- Full command reference: [docs/DLLPickle.md](docs/DLLPickle.md) +- Changelog and active work: [CHANGELOG.md](CHANGELOG.md) +- Architecture blueprint and planned enhancements: [docs/Architecture.md](docs/Architecture.md) +- Dependency, versioning, and supply-chain policy: [DEPENDENCIES.md](DEPENDENCIES.md) +- Contribution workflow: [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) +- Security vulnerability reporting: [SECURITY.md](SECURITY.md) diff --git a/docs/DLLPickle.md b/docs/DLLPickle.md index b8c46e84..60854c2d 100644 --- a/docs/DLLPickle.md +++ b/docs/DLLPickle.md @@ -46,6 +46,14 @@ Gets modules and sorts them by packaged `Microsoft.Identity.Client.dll` version. Imports DLLPickle dependency libraries. +### [Import-DPBaseProfile](DLLPickle/Import-DPBaseProfile.md) + +Runs `Import-DPLibrary` and imports the validated base-profile modules (Exchange Online, Microsoft Teams, Microsoft Graph, and Az.Accounts) in a known-good order. + +### Test-DPLibraryConflict + +Reports known-incompatible module combinations loaded in the current session (for example the Az.Storage + ExchangeOnlineManagement OData conflict, issue #174), with the reason and the separate-process workaround. _(The per-command help page is generated during the in-progress `Microsoft.PowerShell.PlatyPS` migration.)_ + ## Archived Commands The following pages are retained for historical reference and migration guidance. diff --git a/docs/Deep-Dive.md b/docs/Deep-Dive.md index 76f3e441..ec3bbd5e 100644 --- a/docs/Deep-Dive.md +++ b/docs/Deep-Dive.md @@ -17,6 +17,19 @@ load errors. DLLPickle addresses this by loading a compatible set of identity-related assemblies before other modules attempt their own assembly loads. +## Related Issues + +This class of conflict is widely reported across Microsoft's first-party +PowerShell modules: + +- [Connect-MgGraph fails after Connect-ExchangeOnline](https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/3394) +- [UUF Customer feedback: Get-EntraExtensionProperty error](https://github.com/microsoftgraph/entra-powershell/issues/1258) (Assembly with same name is already loaded) +- [Assembly with same name is already loaded](https://github.com/microsoftgraph/entra-powershell/issues/1083) +- [Design entra-powershell with ALC bridge pattern for more robust assembly load handling](https://github.com/microsoftgraph/entra-powershell/issues/1242) +- [Implement proper assembly isolation to play nice with vscode-powershell](https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/2978) +- [Conflict with the .NET DLL of the Az module (vscode-powershell#3012)](https://github.com/PowerShell/vscode-powershell/issues/3012) +- [Unable to load Az modules โ€” Assembly with same name is already loaded (vscode-powershell#4727)](https://github.com/PowerShell/vscode-powershell/issues/4727) + ## How DLLPickle Works `Import-DPLibrary` loads DLLs from the module's packaged `bin` folder that diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index b33f22e6..e2eb2049 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -120,12 +120,20 @@ add `Azure.Core.dll` to `Set-DPConfig -SkipLibraries` as a safeguard. ### Issue #174: Az.Storage and ExchangeOnlineManagement OData -Az.Storage 9.6.0 imports `Microsoft.OData.Core` 7.6.4. ExchangeOnlineManagement -3.9.2 can later request `Microsoft.OData.Core` 7.22.0 from `Get-EXO*` cmdlets. -Preloading OData 7.22.0 from DLLPickle was tested and rejected because it -breaks Az.Storage import with an assembly collision against its 7.6.4 copy. - -The safe repro tests keep this scenario visible but do not treat OData -preloading as a supported fix. If both modules need incompatible OData versions, -run the Az.Storage and ExchangeOnlineManagement work in separate PowerShell -processes so each process has its own assembly load context. +Az.Storage (9.6.1) loads `Microsoft.OData.Core` 7.6.4 at import; ExchangeOnlineManagement +(3.9.2) needs 7.22.0 for its `Get-EXO*` cmdlets. Both load into the **default** +`AssemblyLoadContext` and are strong-named, so the two versions cannot coexist in one +process. A 2026-06-01 runtime probe confirmed that **both import orders fail**: + +- Az.Storage first, then `Get-EXO*` → fails (wants 7.22.0, but 7.6.4 is already loaded). +- ExchangeOnlineManagement first, then `Import-Module Az.Storage` → fails (wants 7.6.4, but 7.22.0 is already loaded). + +DLLPickle cannot resolve this by preloading โ€” preloading either version breaks the other +module โ€” so the OData assemblies stay on the block list. As of **2.2.0**, DLLPickle ships +`Test-DPLibraryConflict` (and `Import-DPLibrary` surfaces the same warning automatically) to +flag the conflict when both modules are loaded, with the reason and the workaround below. + +**Workaround:** run the Az.Storage and ExchangeOnlineManagement (`Get-EXO*`) work in separate +PowerShell processes so each process has its own assembly load context. A separate runspace in +the *same* process does **not** help (the conflict is process-wide). The safe repro tests keep +this scenario visible but do not treat OData preloading as a supported fix. From 4a9e9bf5e567a3b5af7bb239a44806643c639cea Mon Sep 17 00:00:00 2001 From: Sam Erde <20478745+SamErde@users.noreply.github.com> Date: Tue, 2 Jun 2026 13:39:56 -0400 Subject: [PATCH 2/2] docs: address Copilot review on #235 - DEPENDENCIES.md Versioning: the bump is derived SOLELY from conventional commit prefixes (Get-VersionBump.ps1), not from detecting dependency/MSAL version changes. Rewrite the table to list the actual prefixes and reframe the dependency guidance as "label the PR with the right prefix." - Troubleshooting.md #174: stop over-promising the automatic warning. Describe the Import-DPLibrary watcher as best-effort/advisory (it can't fire if the second module's import fails before any assemblies load); Test-DPLibraryConflict is the reliable on-demand check. Co-Authored-By: Claude Opus 4.8 --- DEPENDENCIES.md | 23 +++++++++++++++-------- docs/Troubleshooting.md | 10 +++++++--- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md index 957b2e9b..ed038dd0 100644 --- a/DEPENDENCIES.md +++ b/DEPENDENCIES.md @@ -31,14 +31,21 @@ For usage guidance, see [README.md](README.md) and [docs/index.md](docs/index.md DLLPickle follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). Releases are cut automatically by the **Release-and-Publish** workflow, which -derives the bump from [Conventional Commits](https://www.conventionalcommits.org/) -since the last tag: - -| Bump | Trigger | -| ---- | ------- | -| **MAJOR** (`X.y.z`) | A breaking change (a `!` / `BREAKING CHANGE` commit), or a bundled MSAL **major** version increment. | -| **MINOR** (`x.Y.z`) | A new feature (`feat:`), or a new / updated bundled dependency โ€” including the automated MSAL and identity-library version bumps that are the module's core purpose. | -| **PATCH** (`x.y.Z`) | Fixes (`fix:`), refactors, performance/logging tweaks, and other non-breaking corrections. | +derives the bump **solely from the [Conventional Commit](https://www.conventionalcommits.org/) +prefixes** of the commits since the last tag (see +[`.github/ci-scripts/Get-VersionBump.ps1`](.github/ci-scripts/Get-VersionBump.ps1)): + +| Bump | Commit prefix | +| ---- | ------------- | +| **MAJOR** (`X.y.z`) | `BREAKING CHANGE:`, `breaking:`, or `major-release` | +| **MINOR** (`x.Y.z`) | `feat:` (or `minor:`) | +| **PATCH** (`x.y.Z`) | `fix:`, `perf:`, `refactor:`, `security:`, or `chore:` | + +The bump is decided by the commit prefix alone โ€” there is **no** separate +detection of dependency or MSAL version changes. Label dependency-update PRs +accordingly: the automated MSAL / identity-library bumps that are the module's +core purpose should land as `feat:` so they produce a **minor** release, and a +bundled-library **major** jump should be committed as a breaking change. A new PowerShell Gallery version is published **only** when a change affects the published module bundle (`src/DLLPickle/**` or the bundled package set). CI-, diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index e2eb2049..cf871475 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -129,9 +129,13 @@ process. A 2026-06-01 runtime probe confirmed that **both import orders fail**: - ExchangeOnlineManagement first, then `Import-Module Az.Storage` → fails (wants 7.6.4, but 7.22.0 is already loaded). DLLPickle cannot resolve this by preloading โ€” preloading either version breaks the other -module โ€” so the OData assemblies stay on the block list. As of **2.2.0**, DLLPickle ships -`Test-DPLibraryConflict` (and `Import-DPLibrary` surfaces the same warning automatically) to -flag the conflict when both modules are loaded, with the reason and the workaround below. +module โ€” so the OData assemblies stay on the block list. As of **2.2.0**, run +`Test-DPLibraryConflict` to reliably check the current session and warn (with the reason and +the workaround below) whenever both modules are loaded. `Import-DPLibrary` also arms a +**best-effort, advisory** watcher that surfaces the same warning if the pair becomes co-loaded +later โ€” but it cannot catch every case (for example, if the second module's import fails before +any of its assemblies load, no `AssemblyLoad` event fires), so `Test-DPLibraryConflict` is the +reliable check. **Workaround:** run the Az.Storage and ExchangeOnlineManagement (`Get-EXO*`) work in separate PowerShell processes so each process has its own assembly load context. A separate runspace in