NTFSSecurity/Docs/Contributing/05-Releasing.md

Release a new version

This page explains how a maintainer releases a new version of NTFSSecurity. The CI workflow does the work: when you push a version tag, it builds and tests the module, publishes the package to the PowerShell Gallery, and creates the GitHub release with NTFSSecurity.zip.

Prepare the repository once

1. In the PowerShell Gallery, create an API key for the account that owns NTFSSecurity. Select the scope Push new versions of existing packages, enter NTFSSecurity as the glob pattern, and choose an expiration.

2. In the settings of the repository on GitHub, under Environments, create the environment powershell-gallery. To approve every release before it's published, add yourself as a required reviewer. Under Deployment branches and tags, allow only tags such as [0-9]*.[0-9]*.[0-9]*.

3. Add the API key as the secret PSGALLERY_API_KEY of the environment. The command asks for the key:

   gh secret set PSGALLERY_API_KEY --env powershell-gallery --repo raandree/NTFSSecurity
   

Renew the API key before it expires, and update the secret.

Versions

• ModuleVersion in NTFSSecurity\NTFSSecurity.psd1 and the AssemblyVersion and AssemblyFileVersion of the NTFSSecurity, Security2, and PrivilegeControl projects carry the same version. The tests in Tests\Manifest.Tests.ps1 check this.
• A prerelease, such as 5.0.0-rc1, has its label in Prerelease under PrivateData.PSData of the module manifest. Its release notes are the [Unreleased] section of CHANGELOG.md. The PowerShell Gallery installs a prerelease only when you add -AllowPrerelease.
• A release, such as 5.0.0, has no Prerelease value. Its release notes are the section ## [5.0.0] - <date> of CHANGELOG.md.

The tests in Tests\Release.Tests.ps1 check that CHANGELOG.md has the release notes for the version of the module manifest and test the release scripts. The tests in Tests\Repository.Tests.ps1 check the release metadata: the description that the PowerShell Gallery shows, that the version isn't one that the Gallery already has, and that Docs/README.md names no prerelease version. Name a prerelease only in CHANGELOG.md, because the documentation home outlives it.

Publish a prerelease

1. Set the version and the Prerelease label, such as rc1, and make sure that the [Unreleased] section of CHANGELOG.md describes the changes. Add the version that the Gallery has now to $publishedVersions in Tests/Repository.Tests.ps1, so that a test catches a version that is reused. Merge the change into master.

2. Tag the commit on master with the version and push the tag:

   git switch master
   git pull
   git tag 5.0.0-rc1
   git push origin 5.0.0-rc1
   

3. Watch the CI run of the tag. The Release job checks that the tag matches the version in the module manifest and points to a commit on master. Then it publishes the package and creates a GitHub prerelease. If the environment requires a reviewer, approve the deployment.

4. Install the prerelease in a test environment and test it:

   Install-Module -Name NTFSSecurity -AllowPrerelease -Scope CurrentUser
   

For another prerelease, increase the label, such as rc2. The PowerShell Gallery compares labels as text, so rc10 sorts before rc2.

Publish a release

Before you publish a release, run the live tests in a lab against the last prerelease from the PowerShell Gallery, as the acceptance of a release candidate describes, with -Version instead of -ModulePath.

1. Remove the Prerelease value from the module manifest.

2. In CHANGELOG.md, rename ## [Unreleased] to the version with the release date, such as ## [5.0.0] - 2026-10-31, add an empty ## [Unreleased] section above it, and update the links at the end of the file:

   [Unreleased]: https://github.com/raandree/NTFSSecurity/compare/5.0.0...HEAD
   [5.0.0]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...5.0.0
   

3. Merge the change into master. Then tag the commit with the version, such as 5.0.0, and push the tag, as for a prerelease. The Release job warns if the date in CHANGELOG.md isn't the day of the release.

If a release fails

The Release job skips a version that the PowerShell Gallery already has only after its published SHA-512 matches the exact package from the build artifact. It also skips a GitHub release that already exists. If the failure doesn't need a change in the repository, fix the cause and rerun the failed job.

An upload can report an error even after the Gallery accepted it, for example a timeout followed by HTTP 409 (version already exists). The publication script checks the Gallery once more and recovers only if the published SHA-512 verifies the exact local package. A missing version, unavailable metadata, or a different package remains a failure; an existing version alone is not proof of success. The API key stays in the powershell-gallery environment secret.

If the fix needs a change in the repository and the PowerShell Gallery doesn't have the version yet, delete the tag, merge the fix, and tag the new commit:

git push origin --delete 5.0.0-rc1
git tag --delete 5.0.0-rc1

The PowerShell Gallery never accepts the same version twice. To replace a published version, publish the next one, such as 5.0.0-rc2, and unlist the faulty version.