You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Version Change: 1.1.1 → 1.1.2 (PATCH - product clarification)
4
+
Version Change: 1.2.0 → 1.3.0 (MINOR - expanded build process documentation)
5
5
Date: 2025-10-01
6
6
7
-
Modified Principles:
8
-
- Added preamble clarifying Process-PSModule as an opinionated reusable workflow product
9
-
- Enhanced configuration guidance for consuming repositories
10
-
- Clarified relationship between framework and consuming repos
7
+
Modified Principles: None
11
8
12
9
Added Sections:
13
-
- Product Overview (new section before Core Principles)
10
+
- Build Process Requirements (comprehensive build execution flow documentation)
11
+
- Custom build scripts support
12
+
- Module manifest generation details
13
+
- Root module compilation process
14
+
- Data loading mechanism
15
+
- Class/enum export mechanism
16
+
- Source file processing order
14
17
15
18
Removed Sections: None
16
19
17
20
Templates Status:
18
-
✅ plan-template.md - Updated to reference v1.1.2
21
+
✅ plan-template.md - No changes needed (constitution check references general principles)
19
22
✅ spec-template.md - No changes needed (no constitution-specific requirements)
20
23
✅ tasks-template.md - No changes needed (general task structure applies)
21
24
22
25
Follow-up TODOs:
23
26
- TODO(RATIFICATION_DATE): Determine original constitution adoption date
24
27
25
-
Rationale for PATCH bump:
26
-
- Clarification of product nature and scope without new requirements
27
-
- Added context about opinionated flow and structure
28
-
- Explained configuration mechanism and consuming repo requirements
29
-
- Non-semantic refinement that improves understanding of product purpose
28
+
Rationale for MINOR bump:
29
+
- Added materially expanded guidance on Build-PSModule action execution flow
30
+
- Documented custom build script (*build.ps1) support and execution order
31
+
- Detailed manifest generation process including derived vs. preserved properties
32
+
- Documented root module compilation with specific folder processing order
33
+
- Added data loader and class/enum export mechanism documentation
34
+
- Material expansion that provides actionable build process requirements
35
+
- Consuming repositories now understand complete build automation
30
36
-->
31
37
32
38
# Process-PSModule Constitution
@@ -44,11 +50,197 @@ Rationale for PATCH bump:
44
50
45
51
### Consuming Repository Requirements
46
52
Repositories that consume Process-PSModule workflows MUST:
47
-
- Follow the module source structure documented in framework actions
53
+
- Follow the module source structure documented in framework actions (see Required Module Structure below)
48
54
- Provide configuration file (`.github/PSModule.yml`) with appropriate settings
49
55
- Adhere to the opinionated workflow execution order
50
-
- Reference Process-PSModule workflows using stable version tags
56
+
- Reference Process-PSModule workflows using stable version tags (e.g., `@v4`)
51
57
- Review action README documentation for structure and configuration requirements
58
+
- Use the [Template-PSModule](https://github.com/PSModule/Template-PSModule) repository as a starting point
59
+
60
+
### Required Module Structure
61
+
62
+
**Process-PSModule enforces an opinionated module structure.** Consuming repositories MUST organize their PowerShell module source code in the following structure within the `src/` folder:
63
+
64
+
```
65
+
src/
66
+
├── manifest.psd1 # PowerShell module manifest (optional, auto-generated if missing)
67
+
├── header.ps1 # Code executed at module load start
68
+
├── finally.ps1 # Code executed at module load end
69
+
├── README.md # Documentation reference (points to Build-PSModule)
70
+
├── assemblies/ # .NET assemblies (.dll) to load
71
+
├── classes/
72
+
│ ├── private/ # Private PowerShell classes
73
+
│ └── public/ # Public PowerShell classes (exported)
74
+
├── data/ # Configuration data files (.psd1)
75
+
├── formats/ # Format definition files (.ps1xml)
76
+
├── functions/
77
+
│ ├── private/ # Private functions (not exported)
78
+
│ └── public/ # Public functions (exported to module)
79
+
├── init/ # Initialization scripts
80
+
├── modules/ # Nested PowerShell modules (.psm1)
81
+
├── scripts/ # Script files (.ps1)
82
+
├── types/ # Type definition files (.ps1xml)
83
+
└── variables/
84
+
├── private/ # Private variables
85
+
└── public/ # Public variables (exported)
86
+
```
87
+
88
+
**Structure Details**:
89
+
-**Build-PSModule** action processes this structure and compiles it into a module
90
+
-**Private vs Public**: `private/` folders contain internal implementations; `public/` folders contain exported elements
91
+
-**Optional Components**: Not all folders are required; include only what your module needs
92
+
-**Function Organization**: Functions can be organized in subdirectories (e.g., `functions/public/Get-/Get-Item.ps1`)
93
+
-**Manifest**: If `manifest.psd1` is not provided, Build-PSModule generates one automatically
94
+
-**Documentation**: See [Build-PSModule README](https://github.com/PSModule/Build-PSModule) for complete structure details
95
+
96
+
### Workflow Integration Requirements
97
+
98
+
Consuming repositories MUST create a workflow file (e.g., `.github/workflows/Process-PSModule.yml`) that calls the reusable Process-PSModule workflow:
- Use Template-PSModule as starting point: https://github.com/PSModule/Template-PSModule
119
+
120
+
### Build Process Requirements
121
+
122
+
**Process-PSModule uses the Build-PSModule action to compile module source code into a production-ready PowerShell module.** The build process is automated and opinionated, following a specific execution flow:
123
+
124
+
#### Build Execution Flow
125
+
126
+
1. **Execute Custom Build Scripts** (Optional)
127
+
- Build-PSModule searches for `*build.ps1` files **anywhere in the repository**
128
+
- Scripts are executed in **alphabetical order by filename** (path-independent)
- Other agents: Check for `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `QWEN.md`
224
416
225
-
**For Consuming Repositories**: Follow the opinionated structure and configuration documented in the README files of the GitHub Actions this framework provides.
417
+
**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).
0 commit comments