docs: updated release workflow description

Author: blindzero

docs/advanced/releases.md

@@ -1,79 +1,135 @@
 # Releasing IdLE
 
-This document describes how maintainers cut a release using the GitHub Actions workflow.
+This document describes the **maintainer** release process for IdLE.
 
-> This is part of the **advanced** documentation because it is maintainer-focused and describes repository
-> operations (tags, GitHub Releases, release artifacts) rather than end-user usage.
+IdLE currently ships release artifacts in two channels:
 
-## Prerequisites
+- **GitHub Releases** (always)  
+- **PowerShell Gallery** (stable releases only, guarded by environment approval)
 
-- You have write permissions to the repository.
-- CI is green on `main`.
-- The repository uses **immutable releases** (recommended). Once a release is published, its assets and tag should be treated as write-once.
+Pre-release tags are **GitHub-only** (no PowerShell Gallery publish).
+
+## Principles and guardrails
+
+- **No direct commits to `main`.** Release prep is done via a Pull Request.
+- Tags must be created on the intended `main` commit.  
+- The Release workflow validates that the tag version matches the module manifest versions (fail-fast).
+- Publishing to PowerShell Gallery is protected via a GitHub **Environment** (`psgallery-prod`) and requires approval.
+- A local end-to-end publish test runs in CI (publishes to a local repository, then installs/imports the module).
+
+## Versioning policy
+
+### Stable tags
+
+Stable releases use tags in the form:
+
+- `vMAJOR.MINOR.PATCH` (example: `v0.7.0`)
+
+For stable releases, all shipped module manifests must have:
+
+- `ModuleVersion = MAJOR.MINOR.PATCH`
+
+### Pre-release tags (GitHub only)
+
+Pre-releases use tags in the form:
+
+- `vMAJOR.MINOR.PATCH-<label>` (example: `v0.7.0-preview.1`, `v0.7.0-rc.1`)
+
+**Important:** the module manifests still use the *base* version:
+
+- `ModuleVersion = MAJOR.MINOR.PATCH`
+
+That means: to cut `v0.7.4-preview.1`, the manifests must already be bumped to `0.7.4`.  
+(The Release workflow extracts the base version and validates it against all module manifests.)
+
+Pre-release tags do **not** publish to PowerShell Gallery.
+
+## Release preparation (always via PR)
+
+1. Create a branch for the release preparation (for example: `release/v0.7.0`).
+2. Bump all shipped module versions using the repository tool:
+
+   ```powershell
+   pwsh -NoProfile -File ./tools/Set-IdleModuleVersion.ps1 -TargetVersion 0.7.0
+   ```
+
+3. Run tests:
+
+   ```powershell
+   pwsh -NoProfile -File ./tools/run-tests.ps1
+   ```
+
+4. Commit and push the changes.
+5. Open a Pull Request to `main` and wait for CI to pass.
+6. Merge the Pull Request.
+
+> Tip: Avoid editing module manifests manually. Use `Set-IdleModuleVersion.ps1` to reduce mistakes and keep changes deterministic.
 
 ## Dry-run (no GitHub Release)
 
-Use this to validate release packaging without creating a GitHub Release.
+Use this to validate that the artifact builds correctly without creating a GitHub Release and without tagging.
 
-Important notes:
+1. Start the workflow manually: **Actions → Release → Run workflow**
+2. Select the branch to run on (typically `main`).
+3. Provide a non-SemVer tag label (to avoid version validation), for example:
 
-- The manual run must be executed from a ref that **contains** the workflow (for example `main` or a feature branch).
-  Older tags (for example `v0.6.0`) may not include the `workflow_dispatch` trigger and therefore cannot be used for manual runs.
-- The `tag` input is used for **naming** the artifact and does **not** need to exist as a git tag.
-- For dry-runs, the workflow uploads the **expanded folder contents** as an artifact to avoid a ZIP-in-ZIP experience.
+   - `dryrun-YYYYMMDD`
 
-Steps:
+4. Ensure `publish_release` and `publish_psgallery` are **false**.
 
-1. Go to **GitHub → Actions → Release**.
-2. Click **Run workflow**.
-3. **Use workflow from**: select `main` (or a feature branch that contains the workflow).
-4. Provide a test tag in the input (for example `v0.7.0-test`).
-5. Leave **publish_release** unchecked / `false`.
-6. When the workflow completes, download the artifact from the **Artifacts** section of the run and inspect the contents.
+The workflow uploads an expanded artifact as a workflow run artifact.
 
-This verifies:
+## Cut a GitHub pre-release (tagged)
 
-- deterministic packaging
-- expected include/exclude rules
-- the artifact can be produced on a clean runner
+Use this when you want a GitHub-only preview build.
 
-## Cut a release (published GitHub Release)
+1. Ensure the manifests are bumped to the target base version (PR merged), e.g. `0.7.4`.
+2. Create an annotated tag on the `main` merge commit:
 
-Releases are created from **annotated tags** matching `v*` (for example `v0.7.0`).
+   ```bash
+   git checkout main
+   git pull --ff-only
 
-From a clean working tree on `main`:
+   git tag -a v0.7.4-preview.1 -m "IdLE v0.7.4-preview.1"
+   git push origin v0.7.4-preview.1
+   ```
 
-```powershell
-git checkout main
-git pull --ff-only
+3. The Release workflow will:
+   - Build the ZIP artifact
+   - Create a GitHub Release marked as **pre-release**
+   - Run the local publish test
+   - Skip PowerShell Gallery publishing
 
-# Create an annotated tag (recommended)
-git tag -a v0.7.0 -m "IdLE v0.7.0"
+If you need another preview, repeat with `preview.2`, etc. (no version bump required as long as base version stays the same).
 
-# Push the tag to trigger the Release workflow
-git push origin v0.7.0
-```
+## Cut a stable release (GitHub Release + optional PSGallery publish)
 
-What happens next:
+1. Ensure the manifests are bumped to the target version (PR merged), e.g. `0.7.0`.
+2. Create an annotated tag:
 
-1. The **Release** workflow runs on the tag.
-2. A deterministic ZIP artifact is created.
-3. A GitHub Release is created for the tag, with auto-generated release notes.
-4. The ZIP is uploaded as a release asset.
+   ```bash
+   git checkout main
+   git pull --ff-only
 
-## PowerShell Gallery publishing
+   # Create an annotated tag (recommended)
+   git tag -a v0.7.0 -m "IdLE v0.7.0"
 
-IdLE is published to the PowerShell Gallery as a **single package** named `IdLE`.
+   # Push the tag to trigger the Release workflow
+   git push origin v0.7.0
+   ```
 
-- On tag pushes matching `v*`, the workflow publishes to PSGallery automatically.
-- For manual runs (`workflow_dispatch`), publishing is only performed when **publish_psgallery** is set to `true`.
+3. The Release workflow will:
+   - Build the ZIP artifact
+   - Create a GitHub Release (not marked as pre-release)
+   - Run the local publish test
+   - Run the PSGallery job **only** for stable tags and only after environment approval
 
-### PSGallery API key
+### PowerShell Gallery publishing
 
-Publishing requires a repository secret:
+IdLE is published to the PowerShell Gallery as a **single package** named `IdLE`.
 
-- **Name:** `PSGALLERY_API_KEY`
-- **Value:** a PowerShell Gallery API key with permission to publish the `IdLE` module.
+- On tag pushes matching `v*`, the workflow publishes to PSGallery automatically.
+- For manual runs (`workflow_dispatch`), publishing is only performed when **publish_psgallery** is set to `true`.
 
 ### Package staging
 
@@ -109,6 +165,15 @@ This script copies the `IdLE` meta-module and required nested modules into a loc
 pwsh -NoProfile -File ./tools/New-IdleReleaseArtifact.ps1 -Tag v0.7.0-test -ListOnly
 ```
 
+### Tag was pushed but the workflow fails with a version mismatch
+
+This means the tag version does not match one or more module manifests.
+
+Fix by:
+1. Bumping versions via `Set-IdleModuleVersion.ps1`
+2. Merging the PR
+3. Creating a new tag on the correct commit
+
 ### I want to “redo” a release
 
 With immutable releases enabled, treat published releases as immutable.
@@ -117,3 +182,8 @@ Preferred approach:
 
 1. Fix the issue on `main`.
 2. Cut a new version tag (for example `v0.7.1`).
+
+### The PSGallery publish job is blocked
+
+This is expected when `psgallery-prod` requires approval.  
+Approve the deployment in the workflow run UI, and ensure `PSGALLERY_API_KEY` is set in the environment.