🌟 [Major]: Unified Workflow Configuration

[MariusStorhaug]

User Scenarios & Testing (mandatory)

Primary User Story

As a PowerShell module maintainer managing multiple repositories, I maintain two separate GitHub Actions workflow files (CI.yml and workflow.yml) that perform overlapping functions - one for testing pull requests and another for publishing releases. When I need to update testing logic, dependency versions, or job configurations, I must make identical changes in both files across all repositories. This dual-maintenance creates opportunities for inconsistency, configuration drift, and errors when workflows diverge.

I need a single workflow configuration file that intelligently handles both continuous integration testing on pull requests AND automated release publishing on merges to the main branch. The workflow should detect the triggering event and execute the appropriate pipeline stages, eliminating duplicate configuration while maintaining all existing capabilities.

Acceptance Scenarios

1. Given a pull request is opened to any branch, When the unified workflow executes, Then it runs all test suites, validates module structure, and reports status without attempting any release operations

2. Given a pull request is merged to the main branch, When the unified workflow executes, Then it runs tests, determines the semantic version bump, creates a GitHub release, and publishes the module to the PowerShell Gallery

3. Given I need to update test coverage requirements, When I modify the unified workflow in one repository, Then I only need to update a single file instead of synchronizing changes between CI.yml and workflow.yml

4. Given a workflow fails during the test phase, When reviewing the run logs, Then I can clearly identify which stage failed (test vs. release) and the failure occurs before any release operations are attempted

5. Given I clone the workflow configuration to a new repository, When I customize module-specific settings, Then I modify only one workflow file instead of maintaining consistency across two separate files

Edge Cases

• What happens when a pull request is opened against the main branch but hasn't been merged yet? (Should test only, no release)
• How does the system handle a force push to main that isn't a PR merge? [NEEDS CLARIFICATION: Should force pushes to main trigger releases, or only PR merges?]
• What happens when tests fail during a post-merge run to main? (Should block release operations)
• How does the system handle concurrent PR merges to main? [NEEDS CLARIFICATION: Are there rate limits or queuing mechanisms needed?]
• What happens when the workflow file itself is modified in a PR? (Should test the new workflow configuration before merge)
• How does the system handle manual workflow triggers? [NEEDS CLARIFICATION: Should manual triggers support both test-only and full release modes?]

Requirements (mandatory)

Functional Requirements

ID	Requirement
FR-001	Workflow MUST execute test suite on all pull request events (opened, synchronized, reopened)
FR-002	Workflow MUST execute test suite AND release pipeline on push events to the main branch
FR-003	Workflow MUST block release operations if any test failures occur
FR-004	Workflow MUST determine semantic version bump based on commit messages or pull request labels
FR-005	Workflow MUST create a GitHub release with automatically generated release notes
FR-006	Workflow MUST publish the module to PowerShell Gallery with the determined version
FR-007	Workflow MUST validate module manifest and structure before any operations
FR-008	Workflow MUST provide clear status reporting distinguishing between test and release stages
FR-009	Workflow MUST support the same test configurations as the existing CI.yml workflow
FR-010	Workflow MUST support the same release configurations as the existing workflow.yml
FR-011	Workflow MUST be configurable to skip specific stages based on repository needs [NEEDS CLARIFICATION: Which stages should be optional - tests, releases, publishing?]
FR-012	Workflow MUST use conditional execution to run release stages only on appropriate triggers

Non-Functional Requirements

ID	Requirement
NFR-001	Workflow MUST complete test execution within the same time as current CI.yml workflow (no performance degradation)
NFR-002	Workflow MUST maintain compatibility with all existing GitHub Actions composite actions used in current workflows
NFR-003	Workflow configuration MUST be readable and maintainable by module maintainers without GitHub Actions expertise
NFR-004	Workflow MUST provide execution logs that clearly separate test and release stages for debugging
NFR-005	Workflow MUST be portable across all PSModule framework repositories with minimal customization
NFR-006	Workflow MUST handle race conditions when multiple PRs are merged in quick succession [NEEDS CLARIFICATION: What is acceptable behavior - queue, fail fast, or concurrent execution?]

Quality Attributes Addressed

Attribute	Target Metric
Maintainability	Single workflow file to update instead of two; reduce configuration surface area by 50%
Reliability	Eliminate configuration drift between CI and release workflows; 100% test pass required before release
Usability	Clear stage separation in logs; self-documenting conditional logic
Portability	Reusable across all PSModule repositories with repository-specific variables
Efficiency	No duplicate job execution; optimize for common case (PRs test only)

Constraints (include if applicable)

Constraint	Description
GitHub Actions Runtime	Must execute within GitHub Actions environment using existing runner configurations
Backward Compatibility	Must support all features currently provided by separate CI.yml and workflow.yml files
PowerShell Gallery API	Must authenticate and publish using existing API key management approach
Semantic Versioning	Must follow semver conventions for version bumping (major.minor.patch)
Existing Composite Actions	Must continue using PSModule/GitHub-Script@v1 and PSModule/Install-PSModuleHelpers@v1

Key Entities (include if feature involves data)

Entity	Description
Workflow Configuration	Single YAML file containing job definitions, conditional logic, and stage orchestration for both CI and release pipelines
Trigger Context	Event information (pull_request vs. push) and branch context determining which pipeline stages execute
Test Results	Output from test suite execution including pass/fail status, coverage metrics, and validation results
Version Metadata	Semantic version number determined from commit messages, PR labels, or conventional commit patterns
Release Artifact	Built module package with manifest, validated structure, ready for publication
Publication Status	Results of publishing to PowerShell Gallery including version, timestamp, and success confirmation

---

Feature Branch: 001-unified-workflow-config
Created: 2025-10-02
Status: Draft

[MariusStorhaug]

---

Feature Branch: 001-unified-workflow

This specification has been created and is ready for the next phase. Use /clarify to address the clarification points or /plan to begin implementation planning.