feat: Migrate to unified CI and release workflow; deprecate CI.yml and enhance workflow documentation

Author: MariusStorhaug

.github/workflows/CI.yml

@@ -1,3 +1,8 @@
+# ⚠️ DEPRECATED: This workflow is deprecated as of Process-PSModule v5.0.0
+# Please migrate to using workflow.yml which now handles both CI and Release operations.
+# Migration guide: https://github.com/PSModule/Process-PSModule/blob/main/docs/migration/v5-unified-workflow.md
+# This file will be removed in v6.0.0
+
 name: Process-PSModule - CI
 
 on:

.github/workflows/workflow.yml

@@ -325,8 +325,30 @@ jobs:
       Verbose: ${{ inputs.Verbose }}
       Version: ${{ inputs.Version }}
 
+  # ============================================================================
+  # CONDITIONAL PUBLISHING JOBS (CI + Release Mode Only)
+  # ============================================================================
+  # The following jobs execute ONLY when changes are merged to the default branch
+  # or pushed directly to the default branch. They are SKIPPED in CI-Only mode.
+  #
+  # CI-Only Mode (Tests Without Publishing):
+  #   - Triggered by: Unmerged PRs, manual triggers, scheduled runs, non-default branch pushes
+  #   - Behavior: All CI tests execute; publish jobs are skipped
+  #   - Use Cases: PR validation, nightly testing, feature branch testing
+  #
+  # CI + Release Mode (Tests With Publishing):
+  #   - Triggered by: Merged PRs to default branch, direct pushes to default branch
+  #   - Behavior: All CI tests execute; if tests pass, publish jobs execute
+  #   - Use Cases: Production releases, hotfix deployments
+  #
+  # Conditional Logic:
+  #   - Tests must pass (Get-TestResults, Get-CodeCoverage success)
+  #   - Workflow must not be cancelled
+  #   - Trigger must be EITHER merged PR OR push to default branch
+  # ============================================================================
+
   Publish-Site:
-    if: ${{ needs.Get-TestResults.result == 'success' && needs.Get-CodeCoverage.result == 'success' && needs.Build-Site.result == 'success' && !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.merged == true }}
+    if: ${{ needs.Get-TestResults.result == 'success' && needs.Get-CodeCoverage.result == 'success' && needs.Build-Site.result == 'success' && !cancelled() && ((github.event_name == 'pull_request' && github.event.pull_request.merged == true) || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))) }}
     needs:
       - Get-Settings
       - Get-TestResults
@@ -347,7 +369,7 @@ jobs:
         uses: actions/deploy-pages@v4
 
   Publish-Module:
-    if: ${{ needs.Get-Settings.result == 'success' && needs.Get-TestResults.result == 'success' && needs.Get-CodeCoverage.result == 'success' && needs.Build-Site.result == 'success' && !cancelled() && github.event_name == 'pull_request' }}
+    if: ${{ needs.Get-Settings.result == 'success' && needs.Get-TestResults.result == 'success' && needs.Get-CodeCoverage.result == 'success' && needs.Build-Site.result == 'success' && !cancelled() && ((github.event_name == 'pull_request' && github.event.pull_request.merged == true) || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))) }}
     needs:
       - Get-Settings
       - Get-TestResults

.specify/memory/constitution.md

@@ -1,3 +1,45 @@
+<!--
+Sync Impact Report - Constitution Amendment v1.6.0 → v1.6.1
+Date: 2025-01-21
+
+Version Change: 1.6.0 → 1.6.1 (PATCH - clarifications and expanded guidance)
+
+Modified Sections:
+- "Pull Request Workflow and Publishing Process" → Updated conditional execution section
+  - Added "Workflow Operating Modes (v5.0.0+)" subsection documenting CI-Only vs CI+Release modes
+  - Updated Publish-Site condition to include push to default branch support
+  - Updated Publish-Module condition to include push to default branch support
+  - Added new row to Publishing Behavior Examples table for "Push to default branch" trigger
+  - Updated Key Points to document push event triggering normal releases
+
+Added Sections:
+- Workflow Operating Modes (v5.0.0+): CI-Only Mode and CI+Release Mode descriptions
+
+Removed Sections:
+- None
+
+Deprecated Sections:
+- None
+
+Templates Requiring Updates:
+- ✅ .specify/templates/plan-template.md - No changes needed (Constitution Check section remains valid)
+- ✅ .specify/templates/spec-template.md - No changes needed (scope/requirements alignment unchanged)
+- ✅ .specify/templates/tasks-template.md - No changes needed (task categorization unchanged)
+- ✅ .github/prompts/constitution.prompt.md - No changes needed (process remains valid)
+
+Follow-up TODOs:
+- None
+
+Replacement Items Needing Confirmation:
+- None
+
+Rationale:
+Expanded the "Pull Request Workflow and Publishing Process" section to document the unified CI/Release
+workflow implementation (feature 001-merge-ci-release-workflows). Added clarity on the two operating modes
+(CI-Only for validation, CI+Release for publishing) and documented push to default branch support for
+releases. This is a PATCH increment as it clarifies existing functionality without changing core principles.
+-->
+
 # Process-PSModule Constitution
 
 ## Product Overview
@@ -475,23 +517,41 @@ The Process-PSModule workflow uses **dynamic conditions** to determine job execu
 
 #### Conditional Execution (Based on PR State and Labels)
 
+**Workflow Operating Modes** (v5.0.0+):
+
+The unified workflow.yml operates in two modes:
+
+1. **CI-Only Mode**: Executes all build and test jobs without publishing
+   - Triggered by: unmerged PRs, scheduled runs, manual triggers
+   - Validates code quality and functionality
+   - Publishing jobs (Publish-Module, Publish-Site) are skipped
+
+2. **CI + Release Mode**: Executes all build/test jobs AND publishes artifacts
+   - Triggered by: merged PRs to default branch, direct pushes to default branch
+   - Publishes module to PowerShell Gallery
+   - Deploys documentation to GitHub Pages
+   - Creates GitHub Release with version tag
+
 **Publish-Site** (GitHub Pages deployment):
 
-- **Executes when**: PR is **merged** to default branch AND tests pass
+- **Executes when**:
+  - PR is **merged** to default branch AND tests pass, OR
+  - Direct **push to default branch** AND tests pass
 - **Skipped when**: PR is open/synchronized OR not merged OR scheduled run OR manual trigger
-- Condition: `github.event_name == 'pull_request' AND github.event.pull_request.merged == true`
+- Condition: `((github.event_name == 'pull_request' AND github.event.pull_request.merged == true) OR (github.event_name == 'push' AND github.ref == format('refs/heads/{0}', github.event.repository.default_branch))) AND tests pass`
 
 **Publish-Module** (PowerShell Gallery publishing):
 
 - **Executes when**:
   - PR is **merged** to default branch AND tests pass (normal release), OR
+  - Direct **push to default branch** AND tests pass (normal release), OR
   - PR has **`prerelease` label** AND PR is **not merged** AND tests pass (prerelease)
 - **Skipped when**:
   - PR has `NoRelease` label, OR
   - Scheduled run (cron trigger), OR
   - Manual run (workflow_dispatch), OR
   - Tests fail
-- Condition: `(github.event_name == 'pull_request' AND github.event.pull_request.merged == true) OR (labels contains 'prerelease' AND NOT merged)`
+- Condition: `((github.event_name == 'pull_request' AND github.event.pull_request.merged == true) OR (github.event_name == 'push' AND github.ref == format('refs/heads/{0}', github.event.repository.default_branch))) OR (labels contains 'prerelease' AND NOT merged)`
 
 ### Publishing Behavior Examples
 
@@ -508,6 +568,7 @@ The Process-PSModule workflow uses **dynamic conditions** to determine job execu
 | Merged | (no label) | ✅ Yes | ✅ Yes (if AutoPatching) | ✅ Yes | `1.2.4` (patch) |
 | Merged | `NoRelease` | ✅ Yes | ❌ No | ❌ No | N/A (skipped) |
 | Merged | `prerelease`, `minor` | ✅ Yes | ✅ Yes (normal) | ✅ Yes | `1.3.0` (prerelease ignored) |
+| Push to default branch | N/A | ✅ Yes | ✅ Yes (normal) | ✅ Yes | `1.2.4` (patch) |
 | Scheduled (cron) | N/A | ✅ Yes | ❌ No | ❌ No | N/A (validation only) |
 | Manual (workflow_dispatch) | N/A | ✅ Yes | ❌ No | ❌ No | N/A (validation only) |
 
@@ -589,6 +650,7 @@ jobs:
 **Key Points**:
 
 - **`closed` event** with `github.event.pull_request.merged == true` triggers normal releases
+- **`push` event** to default branch triggers normal releases (supports direct pushes and branch protection bypass)
 - **`labeled` event** allows immediate prerelease publishing when `prerelease` label added
 - **`synchronize` event** with `prerelease` label publishes new prerelease on each push
 - **Secrets** MUST include `APIKEY` for PowerShell Gallery publishing (optional for CI-only runs)
@@ -745,4 +807,4 @@ For agent-specific runtime development guidance **when developing the framework*
 
 **For Consuming Repositories**: Follow the Required Module Structure and Workflow Integration Requirements documented in the Product Overview section. Start with [Template-PSModule](https://github.com/PSModule/Template-PSModule).
 
-**Version**: 1.6.0 | **Ratified**: TODO(RATIFICATION_DATE) | **Last Amended**: 2025-10-01
+**Version**: 1.6.1 | **Ratified**: TODO(RATIFICATION_DATE) | **Last Amended**: 2025-01-21

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to Process-PSModule will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.0] - TBD
+
+### 🌟 Breaking Changes
+
+- **Unified CI and Release Workflow**: Consolidated separate CI.yml and workflow.yml into a single intelligent workflow
+  - CI.yml is now **deprecated** and will be removed in v6.0.0
+  - workflow.yml now handles both CI-only testing (unmerged PRs, manual triggers) and CI + release operations (merged PRs, direct pushes to main)
+  - Automatic conditional execution based on trigger context
+  - For repositories using CI.yml: Migration recommended during v5.x lifecycle (see [migration guide](./docs/migration/v5-unified-workflow.md))
+  - For repositories already using workflow.yml: No changes required
+
+### Added
+
+- Conditional execution logic in workflow.yml for intelligent CI-only vs CI + Release mode determination
+- Comprehensive inline documentation explaining workflow execution modes
+- Migration guide for consuming repositories ([docs/migration/v5-unified-workflow.md](./docs/migration/v5-unified-workflow.md))
+- Deprecation notice in CI.yml header with migration instructions
+
+### Changed
+
+- Publish-Module job now conditionally executes only on merged PRs or direct pushes to default branch
+- Publish-Site job now conditionally executes only on merged PRs or direct pushes to default branch
+- Updated README.md with breaking change notice and unified workflow documentation
+- Updated .github/copilot-instructions.md with unified workflow as active technology
+
+### Removed
+
+- None (CI.yml marked deprecated but not removed; removal planned for v6.0.0)
+
+### Migration
+
+**Action Required for Repositories Using CI.yml**:
+1. Update consuming repository workflow to call workflow.yml instead of CI.yml
+2. Consolidate workflow triggers to single workflow file
+3. Test both PR and merge workflows
+4. Remove CI.yml reference after validation
+
+**No Action Required for Repositories Using workflow.yml**:
+- Existing behavior preserved
+- Optional: Update workflow version reference from @v4 to @v5
+
+For detailed migration instructions and validation procedures, see the [v5.0.0 Migration Guide](./docs/migration/v5-unified-workflow.md).
+
+## [4.x] - Previous Releases
+
+For changelog entries prior to v5.0.0, see the [GitHub Releases](https://github.com/PSModule/Process-PSModule/releases) page.

README.md

@@ -16,8 +16,46 @@ Gallery and produces documentation that is published to GitHub Pages. The workfl
    1. Create a new secret in the repository called `APIKEY` and set it to the API key for the PowerShell Gallery.
 1. Create a branch, make your changes, create a PR and let the workflow run.
 
+## ⚠️ Breaking Changes in v5.0.0
+
+**Unified Workflow**: Process-PSModule v5.0.0 consolidates CI and release operations into a single `workflow.yml` file.
+
+### What Changed
+
+- **CI.yml is deprecated**: The separate `CI.yml` workflow is now deprecated and will be removed in v6.0.0
+- **Single workflow for all operations**: `workflow.yml` now handles both CI testing (unmerged PRs) and release operations (merged PRs)
+- **Intelligent conditional execution**: The workflow automatically determines whether to run tests only or tests + release based on trigger context
+
+### Migration Required?
+
+- ✅ **Already using workflow.yml only**: No changes required, your setup continues working
+- ⚠️ **Using CI.yml**: Migration recommended during v5.x; see [migration guide](./docs/migration/v5-unified-workflow.md)
+
+### Why This Change?
+
+- Reduces maintenance burden across all PSModule repositories
+- Eliminates configuration drift between separate workflow files
+- Provides single source of truth for entire CI/CD pipeline
+- Simplifies onboarding for new repositories
+
+For detailed migration instructions, see the [v5.0.0 Migration Guide](./docs/migration/v5-unified-workflow.md).
+
 ## How it works
 
+The unified workflow (`workflow.yml`) intelligently handles both continuous integration testing and automated release publishing based on trigger context.
+
+**CI-Only Mode** (unmerged PRs, manual triggers, scheduled runs):
+- Executes all build and test jobs
+- Skips publish operations
+- Reports test results as PR status checks
+
+**CI + Release Mode** (merged PRs, direct pushes to main):
+- Executes all build and test jobs
+- If tests pass, executes publish operations
+- Publishes module to PowerShell Gallery
+- Deploys documentation to GitHub Pages
+- Creates GitHub release
+
 The workflow is designed to be triggered on pull requests to the repository's default branch.
 When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow will run.
 Depending on the labels in the pull requests, the workflow will result in different outcomes.
@@ -97,7 +135,7 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v2
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       APIKEY: ${{ secrets.APIKEY }}