From cb7fd7ee36f997305b17d316e268bd1cce26b63e Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 21:52:03 +0200 Subject: [PATCH] chore(memory-bank): record the release process and the 5.0.0-rc1 plan - Decision 12: releases are built and published by CI on a version tag, prerelease first; Decision 10 gains the prerelease rule. - techContext and systemPatterns: the release job, the packages, the command tags, and the new tests. - progress and activeContext: #97 merged, the release PR, and the steps for the maintainer. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 44 ++++++++++++---------- .memory-bank/decisions/0010-one-version.md | 19 ++++++---- .memory-bank/decisions/0012-ci-releases.md | 39 +++++++++++++++++++ .memory-bank/progress.md | 41 ++++++++++++-------- .memory-bank/systemPatterns.md | 11 ++++-- .memory-bank/techContext.md | 33 ++++++++++------ 6 files changed, 131 insertions(+), 56 deletions(-) create mode 100644 .memory-bank/decisions/0012-ci-releases.md diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 438b536..1b3907c 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,30 +9,36 @@ source: current task evidence ## Current focus -PRs #94, #95, and #96 are merged; CI and the wiki run on GitHub Actions. -The version history completed from the PowerShell Gallery packages is -PR-ready on the local branch `ai/version-history`; the maintainer pushes it -and opens the PR. Work package 5 (code defects) waits for the maintainer's -go-ahead. +Release 5.0.0 through CI, with the prerelease `5.0.0-rc1` first +(Decision 12). The release workflow, scripts, tests, and docs are PR-ready +on the local branch `ai/release-5.0.0`; the maintainer pushes it, opens the +PR, sets up the Gallery key and the environment `powershell-gallery`, and +tags `5.0.0-rc1` after the merge. Work package 5 (code defects) and the +open issues come after the release. ## Evidence -- Six Gallery packages compared (4.0.0, 4.2.2 to 4.2.6), each imported in - its own Windows PowerShell process: exported cmdlets 30, 35, 36, 36, 36, - 36. `Show-SimpleAccess` was exported only by 4.0.0 (the manifest of 4.2.2 - to 4.2.4 lists it as `Show-NTFSSimpleAccess`) and deleted in 4.2.5. All - versions export the aliases `dir2`, `gi2`, `rm2`, and `del2` only. -- 4.2.4 already carried the MIT license (`LicenseUri`), the setting - `IdentifyHardLinks`, and AlphaFS 2.2.1; 4.2.5 fixed the `-Account` - aliases (#18, #36) and #48 but broke the `Applies to` column, which 4.2.6 - fixed (#57). 4.2.5 and 4.2.6 still ship AlphaFS 2.2.1: `d8f67af` updated - only `packages.config`, not the `HintPath`. -- `Wiki.Tests.ps1` passes with the changed page; markdownlint (with `MD024` - siblings only for `CHANGELOG.md`) and the link check found nothing. +- Test first: `Tests\Release.Tests.ps1` failed 15 of 15 (Windows + PowerShell: 9 failed, 6 skipped) before the scripts existed; the command + tag test failed before the tags were added. Final: full suite 268 tests, + PowerShell 7 232 passed and 36 skipped, Windows PowerShell 261 passed and + 7 skipped (packaging needs PowerShell 7). +- Package dry run: `NTFSSecurity.5.0.0-rc1.nupkg` (about 275 KB) with the 11 + `FileList` files, version `5.0.0-rc1`, release notes link, and 83 tags + (36 `PSCmdlet_`, 36 `PSCommand_`, `PSIncludes_Cmdlet`); the extracted + package imports in Windows PowerShell 5.1 and PowerShell 7.6.1 with 36 + cmdlets and working help. 4.2.6 on the Gallery has 37 + 37 command tags; + PSResourceGet 1.2.0 `Compress-PSResource` adds none. +- actionlint, PSScriptAnalyzer, and markdownlint: no findings. +- `master` has 37 open issues; several overlap the work package 5 defects + (for example #4) or are already fixed (#19 in 4.2.4; #15, #47, #66 by the + documentation). - 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 -After the maintainer opens the PR: read its GitHub Actions run with -`gh pr checks`. Then wait for the go-ahead for work package 5. +After the maintainer opens the PR: read its CI run, and download the +`packages` artifact (`gh run download`) to compare it with the local dry +run. After the `5.0.0-rc1` tag: check the release job, the Gallery entry +(version, tags, `Find-Command Get-NTFSAccess`), and the GitHub prerelease. diff --git a/.memory-bank/decisions/0010-one-version.md b/.memory-bank/decisions/0010-one-version.md index f75f5af..958eb3b 100644 --- a/.memory-bank/decisions/0010-one-version.md +++ b/.memory-bank/decisions/0010-one-version.md @@ -8,17 +8,22 @@ source: maintainer decisions in work package 4 # Decision 10: One version for the manifest, assemblies, and changelog -- Choice: `ModuleVersion` in `NTFSSecurity.psd1`, `AssemblyVersion` and +- Choice: `ModuleVersion` in `NTFSSecurity.psd1` and `AssemblyVersion` and `AssemblyFileVersion` of `NTFSSecurity`, `Security2`, and - `PrivilegeControl` (as `x.y.z.0`), and the latest version section of - `CHANGELOG.md` carry the same version. The vendored `ProcessPrivileges` - and the unshipped `Log` keep their own versions. - `Tests\Manifest.Tests.ps1` enforces this. + `PrivilegeControl` (as `x.y.z.0`) carry the same version + (`Tests\Manifest.Tests.ps1`). The vendored `ProcessPrivileges` and the + unshipped `Log` keep their own versions. `CHANGELOG.md` describes that + version (`Tests\Release.Tests.ps1` through `Get-ReleaseInfo.ps1`): a + release has a dated section `## [x.y.z] - yyyy-MM-dd`; a prerelease has + its label in `PrivateData.PSData.Prerelease` and its notes under + `## [Unreleased]`, with no section for `x.y.z` yet (changelog Option A, + amended 2026-10-04 for the 5.0.0 prerelease). - Rationale: Before, the manifest said 4.2.5, the release 4.2.6, and the assemblies 4.2.1.0, 3.2.3.0, and 1.0.0.0; releases bumped the version only in the published copy. One version, set in the repository before the release, identifies a build. -- Consequence: A version bump changes all five places in one commit. The - date of the version section is the release date; update it when you tag. +- Consequence: A version bump changes the manifest and three assemblies in + one commit. The final release renames `[Unreleased]` to the dated version + section and removes the prerelease label. - Context: 5.0.0 is major because the minimum PowerShell version rose to 5.1. `Remove-Item2 -PassThur` stays as a deprecated alias of `-PassThru`. diff --git a/.memory-bank/decisions/0012-ci-releases.md b/.memory-bank/decisions/0012-ci-releases.md new file mode 100644 index 0000000..118cad0 --- /dev/null +++ b/.memory-bank/decisions/0012-ci-releases.md @@ -0,0 +1,39 @@ +--- +status: accepted +date: 2026-10-04 +last-verified: 2026-10-04 +owner: shared +source: maintainer decisions after #97 (release first, prerelease first) +--- + +# Decision 12: Releases are built and published by CI on a version tag + +- Choice: Pushing a tag such as `5.0.0` or `5.0.0-rc1` on `master` runs the + `release` job of `.github/workflows/ci.yml`. It publishes the package that + the `build` job built and tested to the PowerShell Gallery + (`Publish-PSResource -NupkgPath`) and creates the GitHub release with + `NTFSSecurity.zip`, marked as a prerelease for a prerelease tag. The job + checks that the tag equals the manifest version (with the prerelease + label) and points to a commit on `master`, and it skips a version the + Gallery or GitHub already has, so a rerun is safe. +- Package: `New-ModulePackage.ps1` copies only the `FileList` files of the + Release build, so no `.pdb`, XML documentation, or + `System.Management.Automation.dll` ships. `Compress-PSResource` builds the + nupkg; the script adds the command tags (`PSIncludes_Cmdlet`, + `PSCmdlet_`, `PSCommand_`) that PowerShellGet 2 added and + PSResourceGet 1.2 doesn't, because the Gallery lists cmdlets and + `Find-Command` searches by them. Every CI run builds the packages, so pull + requests test them. +- Secret: `PSGALLERY_API_KEY` belongs to the GitHub environment + `powershell-gallery`, which only the `release` job uses; the maintainer + creates the key, the environment, and the secret, and may require a + reviewer. +- Process: a prerelease first (maintainer, 2026-10-04: "no full release + without proper testing"), starting with `5.0.0-rc1`; the final release + removes the label and dates the changelog section. Steps for maintainers + are in `Docs/Contributing/05-Releasing.md`. +- Rationale: Releases so far were local Debug builds published by hand + with the whole output folder; tags carried the previous version. +- Rejected: publishing with PowerShellGet 2 `Publish-Module` (repackages at + publish time, so the tested package isn't the published one), and adding + the command tags to the shipped manifest. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 9eca350..9e73a97 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -9,12 +9,12 @@ source: repository evidence ## Current status -PRs #91 to #96 are merged; `master` (`4f9f7cc`) carries version 5.0.0, +PRs #91 to #97 are merged; `master` (`59663c9`) carries version 5.0.0, which is not released yet. CI runs on GitHub Actions: build, docs checks, and tests in Windows PowerShell 5.1 and PowerShell 7, plus the wiki, which -is generated from `Docs` (43 pages). AppVeyor no longer reports on `master`. -PR-ready locally: `ai/version-history`, the version history completed from -the PowerShell Gallery packages. +is generated from `Docs` (43 pages). PR-ready locally: `ai/release-5.0.0`, +releases by CI on a version tag (Decision 12), starting with the +prerelease `5.0.0-rc1`. ## Recent milestones @@ -43,9 +43,15 @@ the PowerShell Gallery packages. 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: release dates, notes for 4.2.2, detailed - notes for 4.2.4, and separate notes for 4.2.5 and 4.2.6 - (`ai/version-history`). + 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. ## Stable capabilities @@ -65,19 +71,22 @@ next package starts only after the maintainer's go-ahead. 1. Housekeeping: done (#92). 2. Ship help: done (#93). 3. Docs on GitHub: done (#94). -4. Manifest and version 5.0.0: done (#95). Before the release: set the date - of the 5.0.0 section to the release date (fold the `[Unreleased]` entries - into it), tag `5.0.0` (no `v` prefix), build in Release, and clean - `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity` before - `Publish-Module`; releases so far were Debug builds published with the - whole output folder (`.pdb`, `.xml`, `System.Management.Automation.dll`), - and the removed `NTFSSecurity-Help.xml` would ship again. +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. -4c. Version history from the PowerShell Gallery: PR-ready on - `ai/version-history`. +4c. Version history from the PowerShell Gallery: done (#97). +4d. Release 5.0.0 through CI (Decision 12): PR-ready on `ai/release-5.0.0`. + Before the first tag, the maintainer creates the Gallery API key, the + environment `powershell-gallery`, and its secret `PSGALLERY_API_KEY` + (steps in `Docs/Contributing/05-Releasing.md`). Then: merge, tag + `5.0.0-rc1`, test the prerelease, check its Gallery tags and + `Find-Command`, and for the final release remove the label and date the + changelog section. 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. 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: diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index 913773b..bec4064 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -58,6 +58,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. | 9 | [Keep the documentation on GitHub](decisions/0009-docs-on-github.md) | | 10 | [One version for the manifest, assemblies, and changelog](decisions/0010-one-version.md) | | 11 | [CI and the wiki run on GitHub Actions](decisions/0011-github-actions.md) | +| 12 | [Releases are built and published by CI on a version tag](decisions/0012-ci-releases.md) | ## Patterns @@ -96,6 +97,10 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. 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 one version - (Decision 10). Add a new cmdlet to `CmdletsToExport` and to the expected - count in the same change. + 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. +- `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, + command tags, and `NTFSSecurity.zip` with the module folder. diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index af981f4..649cc21 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -66,9 +66,11 @@ source: repository evidence ## Constraints - `ModuleVersion` on `master` is `5.0.0` (not released); the latest tag and - Gallery release is `4.2.6`. The manifest requires PowerShell 5.1 and .NET - Framework 4.5.2, uses `RootModule`, and lists exactly 36 cmdlets; - `Test-ModuleManifest` passes in Windows PowerShell 5.1 and PowerShell 7.6. + Gallery release is `4.2.6`. On `ai/release-5.0.0`, the manifest adds the + prerelease label `rc1`, so the next tag is `5.0.0-rc1`. The manifest + requires PowerShell 5.1 and .NET Framework 4.5.2, uses `RootModule`, and + lists exactly 36 cmdlets; `Test-ModuleManifest` passes in Windows + PowerShell 5.1 and PowerShell 7.6. - Besides the shipped help file and its tests (#93), the module source at `master` differs from tag `4.2.6` by the `Remove-Item2 -PassThur` to `-PassThru` rename (with a `-PassThur` alias), the manifest changes of @@ -78,12 +80,12 @@ source: repository evidence 4.2.6 (2019-07-12); none has release notes. Older versions were released on CodePlex only, and their dates are lost. The git history starts on 2016-10-10, when the project moved from CodePlex. -- Releases have no script and no CI deployment. Evidence from 4.2.6: the - Gallery DLLs are Debug builds (`DebuggableAttribute` 263), the nuspec - comes from `Publish-Module`, the package holds the whole output folder - (`.pdb`, `AlphaFS.xml`, 7 MB `System.Management.Automation.dll`), and the - published manifest differs from the tag only by `ModuleVersion` (tags - carry the previous version). GitHub releases attach `NTFSSecurity.zip`. +- Releases up to 4.2.6 had no script and no CI deployment: the Gallery + DLLs are Debug builds (`DebuggableAttribute` 263), the nuspec comes from + `Publish-Module`, the package holds the whole output folder (`.pdb`, + `AlphaFS.xml`, 7 MB `System.Management.Automation.dll`), and tags carry + the previous version. From 5.0.0 on, CI publishes on a version tag + (Decision 12). GitHub releases attach `NTFSSecurity.zip`. - CI: GitHub Actions on pull requests and pushes to `master` (Decision 11). AppVeyor no longer reports on `master` (checked on `4f9f7cc`). The Read the Docs project `ntfssecurity` (maintainer `Sup3rlativ3`) and a second @@ -118,8 +120,17 @@ source: repository evidence Windows PowerShell 5.1 and in PowerShell 7. Job `wiki` on `ubuntu-latest` clones the wiki (`gh auth setup-git` with the built-in token), runs `Export-WikiContent.ps1`, lists the changed pages in the job summary, and - publishes from `master` only. Actions are pinned by commit SHA: - `actions/checkout` v7.0.1, `actions/upload-artifact` v7.0.1. + publishes from `master` only. After the tests, `build` runs + `New-ModulePackage.ps1` and uploads the artifact `packages` (nupkg and + `NTFSSecurity.zip`). Job `release` runs only for tags matching + `[0-9]+.[0-9]+.[0-9]+` or `[0-9]+.[0-9]+.[0-9]+-*`, in the environment + `powershell-gallery` (secret `PSGALLERY_API_KEY`); see Decision 12. + Actions are pinned by commit SHA: `actions/checkout` v7.0.1, + `actions/upload-artifact` v7.0.1, `actions/download-artifact` v8.0.1. +- Packaging needs PSResourceGet (`Compress-PSResource`, PowerShell 7.4 or + later); its tests skip in Windows PowerShell. Dry run locally: run + `New-ModulePackage.ps1` against `NTFSSecurity\bin\Release` into + `$env:TEMP`, then extract the nupkg into a folder and import it there. - Read CI runs with `gh run list --repo raandree/NTFSSecurity --workflow ci.yml`, `gh pr checks `, and `gh run view --log-failed` (read-only).