docs: slim the README for new users and refresh the first-level /docs files#235
Merged
Conversation
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 <noreply@anthropic.com>
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
github-actions
Bot
added
the
documentation
Contributor
Up to standards ✅🟢 Issues
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR streamlines the top-level onboarding docs for DLLPickle by slimming the README for new users and refreshing the first-level documentation pages to reflect current behavior (including issue #174 guidance) and the current release/versioning automation.
Changes:
- Condensed
README.mdand updated the exported command list + documentation map. - Refreshed troubleshooting guidance for #174 (Az.Storage ↔ ExchangeOnlineManagement OData conflict) and referenced the conflict-detection tooling.
- Moved and updated versioning/dependency documentation into
DEPENDENCIES.md, and expanded upstream package documentation links.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Slimmed new-user entrypoint; consolidated usage guidance; refreshed command list and doc map. |
| docs/Troubleshooting.md | Updated #174 guidance to reflect current runtime evidence and the recommended workaround. |
| docs/DLLPickle.md | Updated top-level command reference to include newer commands and migration notes. |
| docs/Deep-Dive.md | Added a “Related Issues” section to capture motivating upstream reports. |
| DEPENDENCIES.md | Added explicit versioning policy description and upstream package documentation links. |
- 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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two related pieces of work you asked for: slim the README for new-user accessibility, and review the first-level
/docsfiles for relevancy/accuracy/currency (subdirectoriesDLLPickle/,en-US/,maml/,superpowers/andrequirements.txtwere intentionally excluded).README (171 → 81 lines)
docs/index.mdandDeep-Dive.md).Import-DPBaseProfileandTest-DPLibraryConflict); now all 9, grouped Primary vs Inspection helpers.Troubleshooting.mdto the documentation map.Moved into
/docs:DEPENDENCIES.md.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. If your intended policy differs from what the automation does, say so and I'll adjust.DEPENDENCIES.md.docs/Deep-Dive.mdas motivating background./docsreview findings + fixesindex.mdDeep-Dive.mdArchitecture.mdTroubleshooting.mdTest-DPLibraryConflict(2.2.0), corrected Az.Storage9.6.0→9.6.1DLLPickle.mdImport-DPBaseProfilelinked;Test-DPLibraryConflictunlinked — its per-command page is generated by the in-progress PlatyPS migration)Note:
DLLPickle.mdis PlatyPS-generated; its stale front-matterHelp Version/ms.datewill refresh when theMicrosoft.PowerShell.PlatyPSmigration regenerates it (tracked in CHANGELOG[Unreleased]).Docs-only — no
src//bundle change, so this does not trigger a release.