diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 09a8f93..853db89 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -31,14 +31,21 @@ then work package 5 (code defects) and the open issues. The local branch - Installed with `Save-PSResource` and copied to `bin\Release`, the module passes the full suite: Windows PowerShell 261 passed, 7 skipped; PowerShell 7 232 passed, 36 skipped. -- The command search (`Find-PSResource -CommandName`) still returned 4.2.6 - at 20:16 UTC, four minutes after publishing; the search index was stale, - because it treated 4.2.6 as the absolute latest version. +- `Find-PSResource -CommandName Get-NTFSAccess -Prerelease` lists + 5.0.0-rc1 since 20:22 UTC; at 20:16 UTC the search index still lagged. +- Repository settings (2026-10-04): no protection or ruleset on `master`; + the `powershell-gallery` environment has no protection rules and no + deployment policy; head branches aren't deleted on merge; no + `dependabot.yml`. Collaborators: `raandree` (admin), `nyanhp` (write). + No AppVeyor webhook or commit status remains; no new issues since May + 2025. - The wiki was republished from `e0f5366`; Home mentions `-AllowPrerelease`. ## Next step -Recheck the command search for 5.0.0-rc1. When the maintainer reports test -results: prepare the final 5.0.0 release PR, or fix what the tests found -and publish `5.0.0-rc2`. +The maintainer tests 5.0.0-rc1. On "final", prepare the final 5.0.0 +release PR on release day; on failures, fix them and publish `5.0.0-rc2`. +Proposed meanwhile, awaiting the maintainer: the repository settings in +`progress.md` item 4e, a Dependabot PR for the pinned actions, and +deleting the merged local branches. Work package 5 starts after 5.0.0. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index a0c55bb..b6e24ea 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -18,52 +18,24 @@ version tag (Decision 12). Next: the maintainer tests 5.0.0-rc1. ## Recent milestones -- 2026-10-02: Memory Bank initialized. PR #91 aligned the documentation - with the code (36 cmdlet pages, conceptual pages, README, `mkdocs.yml`, - `.readthedocs.yml`, `CHANGELOG.md`) and made `appveyor.yml` build the - module and check the docs against that build (Decision 6); squash-merged - as `690d8dd`. -- 2026-10-02: PR #83 (TechNet links) closed by the maintainer as superseded - by #91. -- 2026-10-04: Work package 1 merged as PR #92 with a merge commit - (`d917832`): `promptHistory.md` ignored, Decision 7, Decisions moved to - `decisions/`. -- 2026-10-04: Work package 2 squash-merged as PR #93 (`14799fb`): generated - help file shipped (Decision 8), stale help files removed, `FileList` - complete, `Tests\Help.Tests.ps1` (218 Pester tests), CI steps 03 (help - file current) and 04 (Pester, one Tests-tab entry per test; the NUnit - upload had listed 870), six cmdlet-page links reworded for the help - text. AppVeyor passed 218 of 218 on the PR (54834295) and on `master` - (54834350). -- 2026-10-04: Work packages 3 (#94, `bde59a5`), 4 (#95, `6665825`), and the - move to GitHub Actions (#96, `4f9f7cc`) merged with merge commits: Read - the Docs dropped (Decision 9), version 5.0.0 with a valid manifest - (Decision 10), CI and a wiki generated from `Docs` on GitHub Actions - (Decision 11). The first `master` run (37218869672) passed and published - the wiki (`62ec94a`, 43 pages). -- 2026-10-04: The maintainer kept the version history separate from - `CHANGELOG.md` and had it completed from the six PowerShell Gallery - packages and the commit history (#97, `59663c9`): release dates, notes - for 4.2.2, detailed notes for 4.2.4, and separate notes for 4.2.5 and - 4.2.6. The wiki republished it. -- 2026-10-04: The maintainer chose to release 5.0.0 next, through CI and a - prerelease first (Decision 12): `ai/release-5.0.0` adds the `release` job, - `Get-ReleaseInfo.ps1`, `New-ModulePackage.ps1`, `Tests\Release.Tests.ps1`, - the label `rc1`, and `Docs/Contributing/05-Releasing.md`. The package - dry run found that PSResourceGet drops the command tags that 4.2.6 had; - the script adds them back. -- 2026-10-04: #98 merged (`e0f5366`); the tag `5.0.0-rc1` ran the release - job (run 37230802387), which published to the Gallery at 20:12 UTC and - created the GitHub prerelease. Verified: the Gallery nupkg is - byte-identical to the CI artifact, the GitHub zip to the CI zip; the DLLs - are optimized Release builds; the Gallery shows the prerelease flag, the - release notes link, and 85 tags (36 `PSCmdlet_`, 36 `PSCommand_`, - `PSIncludes_Cmdlet`, plus `PSEdition_Core` and `PSEdition_Desktop`, which - the Gallery adds itself); stable search still returns 4.2.6. Installed - with `Save-PSResource`, the module passes the full suite (Windows - PowerShell 261 passed and 7 skipped, PowerShell 7 232 passed and 36 - skipped). The command search still returned 4.2.6 minutes after - publishing, because the search index lagged. +- 2026-10-02 to 2026-10-04: #91 aligned the docs with the code (Decision + 6; #83 closed as superseded), #92 did housekeeping (Decision 7), and + #93 shipped the generated help file (Decision 8, `Tests\Help.Tests.ps1`). +- 2026-10-04: #94 to #96 dropped Read the Docs (Decision 9), set version + 5.0.0 with a valid manifest (Decision 10), and moved CI and a wiki + generated from `Docs` to GitHub Actions (Decision 11). #97 completed the + version history, kept separate from `CHANGELOG.md`, from the six Gallery + packages and the commit history. +- 2026-10-04: #98 (`e0f5366`) added releases on a version tag through CI + (Decision 12), with a prerelease first; `New-ModulePackage.ps1` adds the + command tags that PSResourceGet drops. The tag `5.0.0-rc1` (run + 37230802387) published to the Gallery at 20:12 UTC and created the + GitHub prerelease. Verified: the Gallery nupkg and the GitHub zip are + byte-identical to the CI artifacts, the DLLs are optimized Release + builds, the Gallery shows the prerelease flag, the release notes link, + and all 36 `PSCmdlet_` and `PSCommand_` tags, and the installed module + passes the full suite (Windows PowerShell 261 passed, 7 skipped; + PowerShell 7 232 passed, 36 skipped). ## Stable capabilities @@ -84,28 +56,41 @@ next package starts only after the maintainer's go-ahead. 2. Ship help: done (#93). 3. Docs on GitHub: done (#94). 4. Manifest and version 5.0.0: done (#95). -4b. CI and the wiki on GitHub Actions: done (#96). Left to the maintainer: - revoke AppVeyor's GitHub access if it is still granted, consider - **Restrict editing to collaborators only** for the wiki, and optionally - ask `Sup3rlativ3` to delete the Read the Docs project. +4b. CI and the wiki on GitHub Actions: done (#96). No AppVeyor webhook or + commit status remains. Optional for the maintainer: delete the AppVeyor + project and revoke its GitHub authorization, check **Restrict editing to + collaborators only** for the wiki, and ask `Sup3rlativ3` to delete the + Read the Docs project. 4c. Version history from the PowerShell Gallery: done (#97). 4d. Release 5.0.0 through CI (Decision 12): 5.0.0-rc1 published and - verified (#98). Next: the maintainer tests the prerelease; recheck - `Find-PSResource -CommandName Get-NTFSAccess -Prerelease`, which should - list 5.0.0-rc1 once the Gallery index catches up. For the final release: - remove the label, rename `[Unreleased]` to `[5.0.0]` with the date, and - tag `5.0.0` (steps in `Docs/Contributing/05-Releasing.md`). Consider - changing the manifest `Description`, which says "Windows PowerShell - Module", before the final release. Releases no longer come from a local - build, so the old manual steps (cleaning - `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, Debug - builds) no longer apply. + verified (#98); the command search lists it since 20:22 UTC. Next: the + maintainer tests the prerelease. The final release PR comes on release + day, because the changelog date should be that day (CI warns + otherwise): remove the label, rename `[Unreleased]` to `[5.0.0]` with + the date, and tag `5.0.0` (steps in `Docs/Contributing/05-Releasing.md`). + Also consider the manifest `Description`, which says "Windows + PowerShell Module", and the `5.0.0-rc1` example in `Docs/README.md`. + Releases no longer come from a local build, so the old manual steps + (cleaning `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, + Debug builds) no longer apply. +4e. Repository settings, proposed to the maintainer on 2026-10-04 (not yet + agreed): the `powershell-gallery` environment has no protection rules + and no deployment policy, so a workflow on any branch can use + `PSGALLERY_API_KEY` (`nyanhp` also has write access); `master` has no + protection or ruleset; head branches aren't deleted on merge; no + `dependabot.yml` updates the SHA-pinned actions; the remote branches + `fix/#34` and `test/transfer` (2023-11-28, two commits each) aren't + merged. 5. Code defects, listed below: `review: on`, one PR per group, regression test first. Pester 5 tests import `NTFSSecurity\bin\Release`, run in a `$env:TEMP` sandbox and in the CI workflow (pattern: `Tests\Help.Tests.ps1`), and skip elevated cases when not elevated; check whether the GitHub Actions Windows runner runs elevated. Each fix - updates its cmdlet page and `CHANGELOG.md`. + updates its cmdlet page and `CHANGELOG.md`. Start by triaging the 37 + open issues (none newer than May 2025): #15, #47, and #66 + (documentation) and #19 (fixed in 4.2.4) can be closed; #4 is defect + (5); #34 has the WIP branch `fix/#34`. The E decisions set the next + version: fixes only 5.0.1, additions 5.1.0, changed defaults 6.0.0. ### Code defects (work package 5) diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index bec4064..aac475a 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -33,10 +33,9 @@ NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, descriptor, and privilege cmdlets) enables Backup, Restore, TakeOwnership, and Security in `BeginProcessing` when `PrivateData.EnablePrivileges` is `$true`, and disables the ones it enabled in `EndProcessing`. -- `PrivateData` switches: `EnablePrivileges` (base cmdlet), - `GetInheritedFrom` (`Get-NTFSAccess`, `Get-NTFSAudit`), - `GetFileSystemModeProperty` and `IdentifyHardLinks` (`Get-ChildItem2`), - `ShowAccountSid` (format file). +- `PrivateData` switches: `EnablePrivileges` (base cmdlet), `GetInheritedFrom` + (`Get-NTFSAccess`, `Get-NTFSAudit`), `GetFileSystemModeProperty` and + `IdentifyHardLinks` (`Get-ChildItem2`), `ShowAccountSid` (format file). - Cmdlets accept either `-Path` (alias `FullName`) or `-SecurityDescriptor` (from `Get-NTFSSecurityDescriptor`); SD sets change the in-memory object until `Set-NTFSSecurityDescriptor` writes it back. @@ -66,18 +65,14 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged. -- GitHub renders the docs (Decision 9), and CI publishes them to the wiki - (Decision 11). The MarkdownLinkCheck step covers only relative links in - `Docs` and ignores anchors; `Tests\Wiki.Tests.ps1` checks every link of - the generated wiki, including anchors (GitHub's slug rules: lowercase, - punctuation removed, spaces to hyphens). Check the links in `README.md` - and `CHANGELOG.md` separately. -- The wiki is generated: edit `Docs`, never the wiki. - `Export-WikiContent.ps1` names a page after its file (`Docs/README.md` - becomes Home), rewrites links, and builds the sidebar from the cmdlet - groups of `Docs/README.md`; a cmdlet missing there fails `Wiki.Tests.ps1`. -- platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages - ASCII-only. + platyPS rewrites non-ASCII punctuation, so keep cmdlet pages ASCII-only. +- GitHub renders the docs (Decision 9); CI publishes them to the wiki + (Decision 11). MarkdownLinkCheck: relative `Docs` links, no anchors; + `Tests\Wiki.Tests.ps1`: every wiki link and anchor (GitHub slug rules). + Neither covers the links in `README.md` and `CHANGELOG.md`. +- The wiki is generated from `Docs`; never edit the wiki. Pages are named + after their files, `Docs/README.md` becomes Home, and its cmdlet groups + form the sidebar; a cmdlet missing there fails `Wiki.Tests.ps1`. - In cmdlet pages, end a sentence with a link: platyPS renders a link as `text (url)` in the help file and drops the space after it. - Verify examples in a `$env:TEMP` sandbox, never on real data; parse every @@ -88,18 +83,14 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. - Pester 5 tests in `Tests/*.Tests.ps1` import `NTFSSecurity\bin\Release\NTFSSecurity.psd1`; CI runs them in Windows PowerShell 5.1 and in PowerShell 7 (Decision 11). -- `Get-Help -Online` is tested with the internal test hook - `BypassOnlineHelpRetrieval`, which returns the URI instead of opening a - browser. In PowerShell 7 the hook also skips the help file, so that test - runs only in Windows PowerShell (36 skipped tests in PowerShell 7); - PowerShell 7 resolves the same URI. -- `.github/scripts/Invoke-Tests.ps1` runs Pester for CI: the counts and the - failed tests go to the job summary, the NUnit file to the `test-results` - artifact, and it fails on failed test files too (`Result -ne 'Passed'`). -- `Tests\Manifest.Tests.ps1` checks the built manifest: `Test-ModuleManifest` - without errors or warnings, exactly 36 cmdlets, and the same version in - the manifest and the assemblies (Decision 10). Add a new cmdlet to - `CmdletsToExport` and to the expected count in the same change. +- `Get-Help -Online` tests use the internal hook `BypassOnlineHelpRetrieval` + (URI instead of a browser); it skips the help file in PowerShell 7, so + those 36 tests run only in Windows PowerShell. +- `.github/scripts/Invoke-Tests.ps1` runs Pester in CI: counts and failures + to the job summary, NUnit to `test-results`; failed test files fail too. +- `Tests\Manifest.Tests.ps1`: `Test-ModuleManifest` without errors or + warnings, exactly 36 cmdlets, one version in manifest and assemblies + (Decision 10). A new cmdlet updates `CmdletsToExport` and that count. - `Tests\Release.Tests.ps1` checks that `CHANGELOG.md` has release notes for the manifest version (dated section, or `[Unreleased]` for a prerelease) and the packages: only `FileList` files, version with label,