From 1d370d96db550b8b4fe6aa4ee0cc0ba9c88a19fc Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 14:14:49 +0200 Subject: [PATCH] chore(memory-bank): record the docs on GitHub and the version decisions - Decision 9: keep the documentation on GitHub; no Read the Docs site, and the wiki is retired. Decision 4 now rests on it. - Work package 3 redefined and PR-ready; work package 4 decisions: PowerShellVersion 5.1, DotNetFrameworkVersion 4.5.2, RootModule, and 5.0.0 with the PassThur alias. - Correct the Windows PowerShell 5.1 recipe (don't clear PSModulePath), and record the local build from the NuGet cache, the link-check limits, and the deleted fork behind the Read the Docs project. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 39 ++++++----- .../decisions/0004-online-help-on-github.md | 7 +- .memory-bank/decisions/0009-docs-on-github.md | 25 +++++++ .memory-bank/progress.md | 68 +++++++++---------- .memory-bank/projectbrief.md | 10 +-- .memory-bank/systemPatterns.md | 7 +- .memory-bank/techContext.md | 48 +++++++++---- 7 files changed, 130 insertions(+), 74 deletions(-) create mode 100644 .memory-bank/decisions/0009-docs-on-github.md diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 6ac2f8d..ed1ff73 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: current task evidence --- @@ -9,26 +9,29 @@ source: current task evidence ## Current focus -Work packages 1 (#92) and 2 (#93) are merged. Next is work package 3 (Read -the Docs), after the maintainer's go-ahead, on the local branch -`ai/read-the-docs`, which so far carries Memory Bank notes only. The -remaining packages and their details are in `progress.md`. +Work package 3 was redefined by the maintainer: no Read the Docs, the docs +stay on GitHub, and the wiki is retired (Decision 9). It is PR-ready on the +local branch `ai/docs-on-github` (`84328dc` plus Memory Bank notes). Work +package 4 (manifest and version) continues next, stacked on it, with the +maintainer's decisions recorded in `progress.md`. ## Evidence -- #92 was merged with a merge commit (`d917832`) and #93 squash-merged - (`14799fb`); the tree of `master` equals the tested `c9fbaf5`. -- AppVeyor: the PR build of #93 (54834295) and the `master` build of - `14799fb` (54834350) each passed 218 of 218 Pester tests, listed once - each on the Tests tab; the `master` build of `d917832` passed too. -- The remote branches `ai/housekeeping` and `ai/ship-help` are deleted, and - so are the local ones. The only unmerged commit, the remote-mutation note - (`9dc2022`), is now `023506c` on `ai/read-the-docs`. -- The agent can't push or open PRs (`techContext.md`, Constraints): it - prepares the commands and PR descriptions, and the maintainer runs them. +- All 256 relative links in `Docs`, `README.md`, and `CHANGELOG.md` resolve, + including 5 anchors checked against GitHub's slug rules; MarkdownLinkCheck + 0.2.0 (CI step 02) finds 0 broken links in `Docs` in Windows PowerShell + 5.1; markdownlint reports 0 issues in the changed pages. +- The documented manual install (`Unblock-File`, `Expand-Archive` into + `$env:ProgramFiles\WindowsPowerShell\Modules`) was tested with the 4.2.6 + zip in a `$env:TEMP` sandbox: the module imports under `RemoteSigned`. + `Expand-Archive` doesn't pass the download mark on; File Explorer's zip + handler does, and the import then fails. +- The wiki stopped at 4.2.4; the Gallery has 4.2.5 (2019-07-11) and 4.2.6 + (2019-07-12), whose notes were reconstructed from `4.2.4..4.2.6`. +- The local branch `ai/read-the-docs` keeps the dropped strict-build work + (`886c874`, `325ec76`); delete it once it is no longer wanted. ## Next step -Wait for the maintainer's go-ahead for work package 3. Nothing on -`ai/read-the-docs` needs pushing before then; its Memory Bank commits go -into the work package 3 PR. +Ask which assemblies follow the module version, then implement work +package 4 test-first on a branch stacked on `ai/docs-on-github`. diff --git a/.memory-bank/decisions/0004-online-help-on-github.md b/.memory-bank/decisions/0004-online-help-on-github.md index 1d4673c..d3f2ecc 100644 --- a/.memory-bank/decisions/0004-online-help-on-github.md +++ b/.memory-bank/decisions/0004-online-help-on-github.md @@ -1,7 +1,7 @@ --- status: accepted date: 2026-10-02 -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: shared source: PR #91 (moved from systemPatterns.md) --- @@ -10,5 +10,6 @@ source: PR #91 (moved from systemPatterns.md) - Choice: `online version` of every cmdlet page is `https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/.md`. -- Rationale: The Read the Docs project builds a stale fork, so its URLs show - outdated pages; GitHub always shows `master`. +- Rationale: GitHub renders the docs of `master`, and there is no other + documentation site (Decision 9). Originally chosen because the Read the + Docs project built a stale fork. diff --git a/.memory-bank/decisions/0009-docs-on-github.md b/.memory-bank/decisions/0009-docs-on-github.md new file mode 100644 index 0000000..58c2477 --- /dev/null +++ b/.memory-bank/decisions/0009-docs-on-github.md @@ -0,0 +1,25 @@ +--- +status: accepted +date: 2026-10-04 +last-verified: 2026-10-04 +owner: shared +source: maintainer decision in work package 3 +--- + +# Decision 9: Keep the documentation on GitHub + +- Choice: The documentation lives in `Docs` and `README.md`, and GitHub + renders it. There is no documentation site: the Read the Docs and MkDocs + configuration is removed. The GitHub wiki is retired: its version history + and installation steps moved to `Docs/Version-History.md` and + `Docs/README.md`, and the maintainer turns the wiki off. +- Rationale: One source of truth that is versioned with the code, reviewed + in pull requests, and checked by AppVeyor. The Read the Docs project + `ntfssecurity` belongs to `Sup3rlativ3` and points to a fork that no + longer exists; a wiki is edited outside pull requests and CI. +- Consequences: `online version` links stay on GitHub (Decision 4). Section + anchors follow GitHub's rules. `Docs/index.md` became `Docs/README.md`, so + that GitHub shows it when you open the `Docs` folder. +- Rejected: taking over or re-importing the Read the Docs project with a + strict MkDocs build (prepared on the local branch `ai/read-the-docs`, not + merged), and publishing `Docs` to the wiki. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 59e0d3b..fee48d5 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -34,6 +34,10 @@ from the 4.2.6 release only by the `Remove-Item2 -PassThru` rename and 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: The maintainer dropped Read the Docs: the docs stay on GitHub + and the wiki is retired (Decision 9). Work package 3 committed locally on + `ai/docs-on-github` (`84328dc`). The strict Read the Docs build prepared + before stays unmerged on the local branch `ai/read-the-docs`. ## Stable capabilities @@ -52,39 +56,35 @@ next package starts only after the maintainer's go-ahead. 1. Housekeeping: done (#92). 2. Ship help: done (#93). -3. Read the Docs, next. The local branch `ai/read-the-docs` exists and so - far carries Memory Bank notes only. The project `ntfssecurity` - (`https://app.readthedocs.org/projects/ntfssecurity/`) is maintained by - GitHub user `Sup3rlativ3` and builds the fork `Sup3rlativ3/NTFSSecurity` - (last build about 2021); the repository side is ready - (`.readthedocs.yml`, `Docs/requirements.txt`). The switch happens in the - Read the Docs dashboard. Give the maintainer exact steps for both - options: (a) `Sup3rlativ3` adds him as maintainer and changes the - repository URL, or (b) he imports `raandree/NTFSSecurity` as a new - project (the slug `ntfssecurity` is taken). Ask before installing Python - for `mkdocs build --strict`. After the switch, confirm a build of - `master`, propose whether the `online version` links move to Read the - Docs (Decision 4), and add a documentation link to `README.md`. Done - when Read the Docs builds `master` of this repository and shows the - current pages. -4. Manifest and version: remove `Show-NTFSSimpleAccess` and the duplicate - inheritance entries from `CmdletsToExport` (exactly 36 cmdlets - exported). Versions disagree: manifest 4.2.5, tag and Gallery 4.2.6, - `AssemblyVersion` 4.2.1.0. Propose the next SemVer version with and - without `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the rename in - #64 is breaking), plus `PowerShellVersion` and `DotNetFrameworkVersion` - (manifest 2.0 and 3.5; the assemblies target .NET Framework 4.5.2), and - ask. Move the `[Unreleased]` entries into the new version section (ask - whether the build-only "Read the Docs build configuration" entry stays, - Decision 7) and align `AssemblyInfo`. No tag or publish. Done when - `Test-ModuleManifest` passes, 36 cmdlets are exported, and CI is green. - Inputs: `Test-ModuleManifest` already fails on - `PowerShellVersion = '2.0'` with `CompatiblePSEditions`; releases are - Debug builds published with the whole output folder (`.pdb`, `.xml`, - `System.Management.Automation.dll`), which `FileList` doesn't list. - Before the next build and `Publish-Module`, clean - `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the removed - `NTFSSecurity-Help.xml` ships again. +3. Docs on GitHub (was: Read the Docs), PR-ready on `ai/docs-on-github`: + Read the Docs and MkDocs configuration removed, `Docs/index.md` renamed + to `Docs/README.md`, the wiki's version history and install steps moved + into `Docs` (with reconstructed notes for 4.2.5 and 4.2.6), contributor + guide updated. After the merge, the maintainer turns the wiki off, points + the notes of releases 4.2.4 and 4.2.6 to `Docs/Version-History.md`, and + may ask `Sup3rlativ3` to delete the Read the Docs project. +4. Manifest and version, in progress, stacked on `ai/docs-on-github`. + Maintainer decisions: `PowerShellVersion` 5.1, `DotNetFrameworkVersion` + 4.5.2, `RootModule` instead of `ModuleToProcess`; version 5.0.0 with + `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the changelog lists + `-PassThur` under Deprecated); the changelog entry about the + documentation site is gone (work package 3). Open: which assemblies + follow the module version. Remove `Show-NTFSSimpleAccess` and the + duplicate inheritance entries from `CmdletsToExport` (exactly 36 + cmdlets exported), move the `[Unreleased]` entries into the 5.0.0 + section, and align `AssemblyInfo`. No tag or publish. Done when + `Test-ModuleManifest` passes in Windows PowerShell 5.1 and PowerShell 7, + 36 cmdlets are exported, the versions agree, and CI is green. + Baseline: `Test-ModuleManifest` fails in both editions + (`CompatiblePSEditions` needs `PowerShellVersion` 5.1) and warns about + `ModuleToProcess`; 41 `CmdletsToExport` entries, 37 unique; versions: + manifest 4.2.5, `NTFSSecurity` 4.2.1.0, `Security2` 3.2.3.0, + `PrivilegeControl` 1.0.0.0, `ProcessPrivileges` 1.5.7.0 (vendored); + `Log` isn't shipped. Releases are Debug builds published with the whole + output folder (`.pdb`, `.xml`, `System.Management.Automation.dll`), which + `FileList` doesn't list. Before the next build and `Publish-Module`, + clean `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the + removed `NTFSSecurity-Help.xml` ships again. 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 `appveyor.yml` (pattern: diff --git a/.memory-bank/projectbrief.md b/.memory-bank/projectbrief.md index 98aa2d7..e349e2b 100644 --- a/.memory-bank/projectbrief.md +++ b/.memory-bank/projectbrief.md @@ -19,8 +19,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`. ## Scope - In scope: module source (`NTFSSecurity`, `Security2`, `PrivilegeControl`, - `ProcessPrivileges`), module manifest and type/format data, the MkDocs - documentation site in `Docs/`, and `README.md`. + `ProcessPrivileges`), module manifest and type/format data, the + documentation in `Docs/` (rendered by GitHub, Decision 9), and + `README.md`. - Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs` exists, but no registry cmdlet is exported. - Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases. @@ -28,8 +29,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`. ## Stakeholders - Maintainer and author: Raimund Andree (`raandree`), per the manifest. -- Documentation contributors: James Smith (`mkdocs.yml` `site_author`); - the AppVeyor documentation build runs under the `Sup3rlativ3` account. +- Documentation contributors: James Smith (`site_author` in the former + `mkdocs.yml`) and `Sup3rlativ3` (#62), who owns the Read the Docs project + `ntfssecurity` and a second AppVeyor project. - End users: To confirm beyond the README summary. ## Acceptance criteria diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index e377dbd..a8bd76d 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -55,6 +55,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. | 6 | [CI checks the docs against a build of the source](decisions/0006-ci-checks-docs-against-build.md) | | 7 | [CHANGELOG lists user-visible changes only](decisions/0007-changelog-user-visible-only.md) | | 8 | [Commit the generated help file and check it in CI](decisions/0008-commit-generated-help.md) | +| 9 | [Keep the documentation on GitHub](decisions/0009-docs-on-github.md) | ## Patterns @@ -62,6 +63,10 @@ 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). AppVeyor's link check covers only + relative links in `Docs` and ignores anchors, so check anchors against + GitHub's slug rules (lowercase, punctuation removed, spaces to hyphens) + and the links in `README.md` and `CHANGELOG.md` separately. - platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages ASCII-only. - In cmdlet pages, end a sentence with a link: platyPS renders a link as diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index cb82cac..53b981c 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -19,8 +19,8 @@ source: repository evidence - Module: `NTFSSecurity.psd1` loads `NTFSSecurity.psm1` (aliases `dir2`, `gi2`, `rm2`, `del2`), `NTFSSecurity.Init.ps1` (Add-Type of the helper assemblies, prepends `NTFSSecurity.format.ps1xml`), and `NTFSSecurity.dll`. -- Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`) - built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS +- Documentation: Markdown in `Docs` and `README.md`, rendered by GitHub; no + documentation site and no wiki (Decision 9). Cmdlet pages are platyPS 0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`. - Help: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`, generated from `Docs/Cmdlets` and committed (Decision 8). @@ -39,11 +39,25 @@ source: repository evidence package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild` fails on the binary resources in `Resources.resx` (MSB3822, MSB3823). - platyPS 0.14.2, Pester 5.7.1, PSScriptAnalyzer, and powershell-yaml are - installed only for PowerShell 7. Windows PowerShell 5.1 imports platyPS - and Pester by full path + installed only for PowerShell 7. Windows PowerShell 5.1, started from + PowerShell 7, imports platyPS and Pester by full path (`~\OneDrive\Documents\PowerShell\Modules\platyPS\0.14.2`, - `C:\Program Files\PowerShell\Modules\Pester\5.7.1`) with - `$env:PSModulePath` cleared. MarkdownLinkCheck is not installed. + `C:\Program Files\PowerShell\Modules\Pester\5.7.1`). Leave + `$env:PSModulePath` alone: PowerShell 7 hands the child the Windows + PowerShell default path, and clearing it leaves Windows PowerShell without + its core modules (Pester fails: `Add-Member` not found). +- MarkdownLinkCheck is not installed, and `Save-Module` crashed (FailFast) + in PowerShell 7.6 on 2026-10-04. Download the 0.2.0 package from + `https://www.powershellgallery.com/api/v2/package/MarkdownLinkCheck/0.2.0` + into `$env:TEMP`, extract it, and import it by path. +- The workstation is ARM64; PowerShell 7 runs as x64 under emulation. + Python 3.12.10 (ARM64) is installed per user with winget, the + maintainer's choice for an MkDocs check that Decision 9 made unnecessary. +- The NuGet cache (`~\.nuget\packages`) holds every build dependency: copy + `alphafs\2.2.1`, `system.management.automation.dll\10.0.10586`, and + `microsoft.netframework.referenceassemblies.net452\1.0.3` into + `packages\.`, and point `CscToolPath` at + `microsoft.net.compilers\4.2.0\tools`. ## Constraints @@ -64,8 +78,11 @@ source: repository evidence published manifest differs from the tag only by `ModuleVersion` (tags carry the previous version). GitHub releases attach `NTFSSecurity.zip`. - CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull - requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are - attached to the fork `Sup3rlativ3/NTFSSecurity`. + requests. The Read the Docs project `ntfssecurity` (maintainer + `Sup3rlativ3`) and a second AppVeyor project are attached to the fork + `Sup3rlativ3/NTFSSecurity`, which no longer exists (GitHub 404, + 2026-10-04). That site still serves pages from 2020 and isn't used + (Decision 9). - `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke test in PowerShell 7.6. - `CHANGELOG.md` lists user-visible changes only; CI and build-only changes @@ -103,10 +120,13 @@ source: repository evidence - Help file: `New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force` must leave `git status` unchanged. - Pester: run detached (`Start-DetachedPowerShell.ps1`) in Windows - PowerShell 5.1; a run without `bin\Release\en-US` must fail. + PowerShell 5.1: the launcher starts `pwsh`, and its payload runs + `powershell.exe -NoProfile -EncodedCommand` with Pester imported by full + path. A run without `bin\Release\en-US` must fail. - Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose (tables, code, and headings excluded) on the conceptual pages. -- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`, - `.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist. -- MkDocs needs Python, which this workstation does not have; `mkdocs build - --strict` was not run. +- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `appveyor.yml`. +- Links: AppVeyor step 02 (MarkdownLinkCheck 0.2.0) checks only relative + links in `Docs`; it strips anchors and skips absolute URLs. Check anchors + against GitHub's heading slugs, and the links in `README.md` and + `CHANGELOG.md`, with a script.