Skip to content

Commit 72425c4

Browse files
MariusStorhaugMariusStorhaug
committed
feat: Complete planning phase for settings-driven workflow configuration
- Add comprehensive research findings on configuration patterns - Define data model for hierarchical configuration system - Create configuration schema contract with JSON validation - Develop quickstart guide for configuration setup - Update GitHub Copilot context with new technical details - Mark planning phases as complete in implementation plan This implements Phase 0 (research) and Phase 1 (design) of the settings-driven workflow configuration feature, establishing the foundation for centralized configuration management in Process-PSModule.
1 parent 48e91f5 commit 72425c4

File tree

7 files changed

+1591
-11
lines changed

7 files changed

+1591
-11
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,18 @@
22

33
## Terminal Commands
44

5-
When executing terminal commands (using `run_in_terminal` or similar tools):
6-
75
- Prefer MCP server calls over command-line tools when possible.
8-
- **ALWAYS** send commands into `pwsh -Command` to ensure proper execution.
9-
- These commands must be enclosed in single quotes.
10-
- Escape any single quotes within the command by doubling them (e.g., `It's` becomes `It''s`).
11-
- Use double quotes for string with variables or expressions inside the single-quoted command.
6+
- When running scripts within the [scripts](../.specify/scripts/) folder, just run them directly (shell is default PowerShell).
7+
- For other commands, send them into `pwsh -Command` to ensure proper execution.
8+
9+
### Quoting in PowerShell
10+
11+
Proper quoting is essential in PowerShell to prevent parsing errors and ensure correct command execution.
12+
13+
- **Direct script execution**: Scripts run directly in PowerShell use standard PowerShell quoting rules. Double quotes expand variables and expressions, while single quotes are literal. No additional shell escaping is needed.
14+
15+
- **Via `pwsh -Command`**: Commands are passed as strings to PowerShell. Enclose the entire command in single quotes to treat it as a literal string. Escape single quotes within the command by doubling them (e.g., `It's` becomes `It''s`). Use double quotes within the command for variable expansion, but ensure the outer single quotes protect the string from shell interpretation.
1216

13-
## Other instructions
17+
For arguments containing single quotes, prefer double-quoting the argument inside the command string.
1418

15-
| Tech | Instruction file |
16-
|------|------------------|
17-
| PowerShell | [pwsh.instructions.md](./instructions/pwsh.instructions.md) |
18-
| Markdown | [md.instructions.md](./instructions/md.instructions.md) |
19+
Example: `pwsh -Command 'Write-Host "I''m Groot"'`

‎specs/001-settings-driven-workflow/contracts/configuration-schema.md‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
# Configuration Schema Contract
2+
3+
## Overview
4+
5+
This contract defines the schema for Process-PSModule configuration files. The schema ensures type safety, validation, and consistent structure across all consuming repositories.
6+
7+
## Schema Definition
8+
9+
### Root Schema
10+
11+
```json
12+
{
13+
"$schema": "https://json-schema.org/draft/2020-12/schema",
14+
"$id": "https://raw.githubusercontent.com/PSModule/Process-PSModule/main/schemas/configuration.schema.json",
15+
"title": "Process-PSModule Configuration",
16+
"description": "Configuration schema for Process-PSModule workflows",
17+
"type": "object",
18+
"properties": {
19+
"version": {
20+
"type": "string",
21+
"pattern": "^\\d+\\.\\d+\\.\\d+$",
22+
"description": "Configuration schema version (semantic versioning)"
23+
},
24+
"workflows": {
25+
"type": "object",
26+
"description": "Workflow-specific configurations",
27+
"patternProperties": {
28+
"^[a-zA-Z][a-zA-Z0-9_-]*$": {
29+
"$ref": "#/definitions/WorkflowConfig"
30+
}
31+
}
32+
},
33+
"environments": {
34+
"type": "object",
35+
"description": "Environment-specific overrides",
36+
"patternProperties": {
37+
"^[a-zA-Z][a-zA-Z0-9_-]*$": {
38+
"$ref": "#/definitions/EnvironmentConfig"
39+
}
40+
}
41+
},
42+
"defaults": {
43+
"type": "object",
44+
"description": "Global default values",
45+
"properties": {
46+
"timeout": {
47+
"type": "integer",
48+
"minimum": 1,
49+
"maximum": 3600,
50+
"description": "Default step timeout in minutes"
51+
},
52+
"retries": {
53+
"type": "integer",
54+
"minimum": 0,
55+
"maximum": 10,
56+
"description": "Default retry count for failed steps"
57+
},
58+
"concurrency": {
59+
"type": "integer",
60+
"minimum": 1,
61+
"maximum": 100,
62+
"description": "Default concurrency limit"
63+
}
64+
}
65+
}
66+
},
67+
"required": ["version"],
68+
"additionalProperties": false,
69+
"definitions": {
70+
"WorkflowConfig": {
71+
"type": "object",
72+
"properties": {
73+
"enabled": {
74+
"type": "boolean",
75+
"description": "Whether this workflow is enabled",
76+
"default": true
77+
},
78+
"triggers": {
79+
"type": "array",
80+
"items": {
81+
"type": "string",
82+
"enum": ["push", "pull_request", "pull_request_target", "schedule", "workflow_dispatch", "release"]
83+
},
84+
"description": "GitHub events that trigger this workflow"
85+
},
86+
"matrix": {
87+
"type": "object",
88+
"description": "Test matrix configuration",
89+
"properties": {
90+
"os": {
91+
"type": "array",
92+
"items": {
93+
"type": "string",
94+
"enum": ["ubuntu-latest", "windows-latest", "macos-latest"]
95+
}
96+
},
97+
"powershell": {
98+
"type": "array",
99+
"items": {
100+
"type": "string",
101+
"pattern": "^7\\.[4-9]\\.\\d+$"
102+
}
103+
}
104+
}
105+
},
106+
"steps": {
107+
"type": "array",
108+
"items": {
109+
"$ref": "#/definitions/StepConfig"
110+
},
111+
"description": "Custom step configurations"
112+
}
113+
},
114+
"additionalProperties": false
115+
},
116+
"EnvironmentConfig": {
117+
"type": "object",
118+
"properties": {
119+
"variables": {
120+
"type": "object",
121+
"description": "Environment-specific variables",
122+
"patternProperties": {
123+
"^[A-Z][A-Z0-9_]*$": {
124+
"type": "string"
125+
}
126+
}
127+
},
128+
"secrets": {
129+
"type": "object",
130+
"description": "References to GitHub secrets",
131+
"patternProperties": {
132+
"^[A-Z][A-Z0-9_]*$": {
133+
"type": "string"
134+
}
135+
}
136+
},
137+
"matrix": {
138+
"type": "object",
139+
"description": "Environment-specific matrix overrides"
140+
}
141+
},
142+
"additionalProperties": false
143+
},
144+
"StepConfig": {
145+
"type": "object",
146+
"properties": {
147+
"name": {
148+
"type": "string",
149+
"description": "Step identifier"
150+
},
151+
"action": {
152+
"type": "string",
153+
"description": "GitHub Action reference (owner/repo@version)",
154+
"pattern": "^[^@]+@[^@]+$"
155+
},
156+
"inputs": {
157+
"type": "object",
158+
"description": "Action input parameters"
159+
},
160+
"conditions": {
161+
"type": "array",
162+
"items": {
163+
"type": "string"
164+
},
165+
"description": "Conditional execution expressions"
166+
},
167+
"timeout": {
168+
"type": "integer",
169+
"minimum": 1,
170+
"maximum": 3600,
171+
"description": "Step timeout in minutes"
172+
}
173+
},
174+
"required": ["name", "action"],
175+
"additionalProperties": false
176+
}
177+
}
178+
}
179+
```
180+
181+
## API Contract
182+
183+
### Configuration Loading API
184+
185+
**Endpoint:** `Get-Settings` Action
186+
187+
**Input Parameters:**
188+
- `config-file`: Path to configuration file (default: `.github/PSModule.yml`)
189+
- `environment`: Target environment (default: auto-detected)
190+
- `strict-validation`: Enable strict schema validation (default: true)
191+
192+
**Output Parameters:**
193+
- `config-json`: Complete configuration as JSON string
194+
- `config-version`: Configuration schema version
195+
- `environment-name`: Detected/active environment
196+
- `validation-errors`: JSON array of validation errors (if any)
197+
198+
**Environment Variables:**
199+
All configuration values exported as `PSMODULE_CONFIG_*` prefixed variables
200+
201+
### Configuration Validation API
202+
203+
**Endpoint:** `Test-Configuration` Action
204+
205+
**Input Parameters:**
206+
- `config-file`: Path to configuration file
207+
- `schema-file`: Path to JSON schema file
208+
- `output-format`: Validation output format (json, text, junit)
209+
210+
**Output Parameters:**
211+
- `is-valid`: Boolean indicating configuration validity
212+
- `error-count`: Number of validation errors
213+
- `warning-count`: Number of validation warnings
214+
- `validation-report`: Detailed validation report
215+
216+
## Error Response Contract
217+
218+
### Validation Error Format
219+
220+
```json
221+
{
222+
"errors": [
223+
{
224+
"type": "schema",
225+
"field": "workflows.build.steps[0].timeout",
226+
"message": "Value must be between 1 and 3600",
227+
"severity": "error",
228+
"line": 45,
229+
"column": 12
230+
}
231+
],
232+
"warnings": [
233+
{
234+
"type": "deprecated",
235+
"field": "workflows.build.legacySetting",
236+
"message": "This setting is deprecated and will be removed in v2.0.0",
237+
"severity": "warning"
238+
}
239+
],
240+
"summary": {
241+
"totalErrors": 1,
242+
"totalWarnings": 1,
243+
"isValid": false
244+
}
245+
}
246+
```
247+
248+
### Runtime Error Format
249+
250+
```json
251+
{
252+
"error": {
253+
"code": "CONFIG_LOAD_FAILED",
254+
"message": "Failed to load configuration file",
255+
"details": {
256+
"file": ".github/PSModule.yml",
257+
"reason": "File not found or inaccessible"
258+
},
259+
"suggestions": [
260+
"Ensure .github/PSModule.yml exists in the repository",
261+
"Check file permissions and repository access"
262+
]
263+
}
264+
}
265+
```
266+
267+
## Version Compatibility
268+
269+
### Schema Version Matrix
270+
271+
| Schema Version | PSModule Version | Breaking Changes | Migration Guide |
272+
|----------------|------------------|------------------|-----------------|
273+
| 1.0.0 | v4.x | Initial release | N/A |
274+
| 1.1.0 | v4.1+ | Added environment overrides | [Migration Guide](migration-1.0-to-1.1.md) |
275+
| 2.0.0 | v5.x | Removed deprecated fields | [Migration Guide](migration-1.x-to-2.0.md) |
276+
277+
### Backward Compatibility Rules
278+
279+
- Minor version increments: Additive changes only
280+
- Major version increments: Breaking changes allowed
281+
- Deprecated fields: Warned for one major version before removal
282+
- Migration tools: Provided for complex schema changes
283+
284+
## Testing Contract
285+
286+
### Configuration Test Scenarios
287+
288+
**Valid Configurations:**
289+
- Minimal configuration with required fields
290+
- Full configuration with all optional fields
291+
- Environment-specific overrides
292+
- Matrix configurations for all platforms
293+
294+
**Invalid Configurations:**
295+
- Missing required fields
296+
- Invalid data types
297+
- Malformed YAML/JSON
298+
- Invalid GitHub Actions references
299+
- Circular references
300+
301+
**Edge Cases:**
302+
- Empty configuration files
303+
- Very large configuration files (>1MB)
304+
- Special characters in field names
305+
- Unicode content
306+
- Comments in YAML files
307+
308+
### Validation Test Contract
309+
310+
**Test Case Format:**
311+
```yaml
312+
test-case:
313+
name: "Valid minimal configuration"
314+
input: ".github/test-config.yml"
315+
expected:
316+
valid: true
317+
errors: []
318+
warnings: []
319+
environment: "development"
320+
```
321+
322+
**Coverage Requirements:**
323+
- 100% schema field coverage
324+
- All validation rules tested
325+
- Error message accuracy
326+
- Performance benchmarks met

0 commit comments

Comments
 (0)