Skip to content

Commit 1aa5895

Browse files
MariusStorhaugMariusStorhaug
committed
📖 Add specification for unified workflow configuration
1 parent 91de5d9 commit 1aa5895

File tree

1 file changed

+133
-0
lines changed
  • specs/001-unified-workflow-config

1 file changed

+133
-0
lines changed

‎specs/001-unified-workflow-config/spec.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Feature Specification: Unified Workflow Configuration
2+
3+
## User Scenarios & Testing *(mandatory)*
4+
5+
### Primary User Story
6+
7+
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.
8+
9+
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.
10+
11+
### Acceptance Scenarios
12+
13+
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
14+
15+
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
16+
17+
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
18+
19+
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
20+
21+
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
22+
23+
### Edge Cases
24+
25+
- What happens when a pull request is opened against the main branch but hasn't been merged yet? (Should test only, no release)
26+
- 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?]
27+
- What happens when tests fail during a post-merge run to main? (Should block release operations)
28+
- How does the system handle concurrent PR merges to main? [NEEDS CLARIFICATION: Are there rate limits or queuing mechanisms needed?]
29+
- What happens when the workflow file itself is modified in a PR? (Should test the new workflow configuration before merge)
30+
- How does the system handle manual workflow triggers? [NEEDS CLARIFICATION: Should manual triggers support both test-only and full release modes?]
31+
32+
## Requirements *(mandatory)*
33+
34+
### Functional Requirements
35+
36+
| ID | Requirement |
37+
|----|-------------|
38+
| **FR-001** | Workflow MUST execute test suite on all pull request events (opened, synchronized, reopened) |
39+
| **FR-002** | Workflow MUST execute test suite AND release pipeline on push events to the main branch |
40+
| **FR-003** | Workflow MUST block release operations if any test failures occur |
41+
| **FR-004** | Workflow MUST determine semantic version bump based on commit messages or pull request labels |
42+
| **FR-005** | Workflow MUST create a GitHub release with automatically generated release notes |
43+
| **FR-006** | Workflow MUST publish the module to PowerShell Gallery with the determined version |
44+
| **FR-007** | Workflow MUST validate module manifest and structure before any operations |
45+
| **FR-008** | Workflow MUST provide clear status reporting distinguishing between test and release stages |
46+
| **FR-009** | Workflow MUST support the same test configurations as the existing CI.yml workflow |
47+
| **FR-010** | Workflow MUST support the same release configurations as the existing workflow.yml |
48+
| **FR-011** | Workflow MUST be configurable to skip specific stages based on repository needs [NEEDS CLARIFICATION: Which stages should be optional - tests, releases, publishing?] |
49+
| **FR-012** | Workflow MUST use conditional execution to run release stages only on appropriate triggers |
50+
51+
### Non-Functional Requirements
52+
53+
| ID | Requirement |
54+
|----|-------------|
55+
| **NFR-001** | Workflow MUST complete test execution within the same time as current CI.yml workflow (no performance degradation) |
56+
| **NFR-002** | Workflow MUST maintain compatibility with all existing GitHub Actions composite actions used in current workflows |
57+
| **NFR-003** | Workflow configuration MUST be readable and maintainable by module maintainers without GitHub Actions expertise |
58+
| **NFR-004** | Workflow MUST provide execution logs that clearly separate test and release stages for debugging |
59+
| **NFR-005** | Workflow MUST be portable across all PSModule framework repositories with minimal customization |
60+
| **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?] |
61+
62+
### Quality Attributes Addressed
63+
64+
| Attribute | Target Metric |
65+
|-----------|---------------|
66+
| **Maintainability** | Single workflow file to update instead of two; reduce configuration surface area by 50% |
67+
| **Reliability** | Eliminate configuration drift between CI and release workflows; 100% test pass required before release |
68+
| **Usability** | Clear stage separation in logs; self-documenting conditional logic |
69+
| **Portability** | Reusable across all PSModule repositories with repository-specific variables |
70+
| **Efficiency** | No duplicate job execution; optimize for common case (PRs test only) |
71+
72+
### Constraints *(include if applicable)*
73+
74+
| Constraint | Description |
75+
|------------|-------------|
76+
| **GitHub Actions Runtime** | Must execute within GitHub Actions environment using existing runner configurations |
77+
| **Backward Compatibility** | Must support all features currently provided by separate CI.yml and workflow.yml files |
78+
| **PowerShell Gallery API** | Must authenticate and publish using existing API key management approach |
79+
| **Semantic Versioning** | Must follow semver conventions for version bumping (major.minor.patch) |
80+
| **Existing Composite Actions** | Must continue using PSModule/GitHub-Script@v1 and PSModule/Install-PSModuleHelpers@v1 |
81+
82+
### Key Entities *(include if feature involves data)*
83+
84+
| Entity | Description |
85+
|--------|-------------|
86+
| **Workflow Configuration** | Single YAML file containing job definitions, conditional logic, and stage orchestration for both CI and release pipelines |
87+
| **Trigger Context** | Event information (pull_request vs. push) and branch context determining which pipeline stages execute |
88+
| **Test Results** | Output from test suite execution including pass/fail status, coverage metrics, and validation results |
89+
| **Version Metadata** | Semantic version number determined from commit messages, PR labels, or conventional commit patterns |
90+
| **Release Artifact** | Built module package with manifest, validated structure, ready for publication |
91+
| **Publication Status** | Results of publishing to PowerShell Gallery including version, timestamp, and success confirmation |
92+
93+
---
94+
95+
**Feature Branch**: `001-unified-workflow-config`
96+
**Created**: 2025-10-02
97+
**Status**: Draft
98+
**Input**: User description: "As a PowerShell module maintainer managing multiple repositories, I need a single workflow configuration that handles both continuous integration testing on pull requests and automated release publishing on merges to the main branch. This eliminates the maintenance burden of keeping two separate workflow files (CI.yml and workflow.yml) synchronized across all my module repositories, reducing configuration complexity and the risk of inconsistencies."
99+
100+
## Review & Acceptance Checklist
101+
102+
*GATE: Automated checks run during main() execution*
103+
104+
### Content Quality
105+
106+
- [x] No implementation details (languages, frameworks, APIs)
107+
- [x] Focused on user value and business needs
108+
- [x] Written for non-technical stakeholders
109+
- [x] All mandatory sections completed
110+
111+
### Requirement Completeness
112+
113+
- [ ] No [NEEDS CLARIFICATION] markers remain (4 markers present - requires stakeholder input)
114+
- [x] Requirements are testable and unambiguous
115+
- [x] Success criteria are measurable
116+
- [x] Scope is clearly bounded
117+
- [x] Dependencies and assumptions identified
118+
119+
---
120+
121+
## Execution Status
122+
123+
*Updated by main() during processing*
124+
125+
- [x] User description parsed
126+
- [x] Key concepts extracted
127+
- [x] Ambiguities marked
128+
- [x] User scenarios defined
129+
- [x] Requirements generated
130+
- [x] Entities identified
131+
- [ ] Review checklist passed (pending clarifications)
132+
133+
---

0 commit comments

Comments
 (0)