33{MODULE_DESCRIPTION}
44
55[ ![ Build Status] ( https://img.shields.io/github/actions/workflow/status/{MODULE_PATH}/ci.yml?branch=main&logo=github&style=flat-square )] ( https://github.com/{MODULE_PATH}/actions/workflows/ci.yml )
6-
7- [ ![ CI] ( https://github.com/{MODULE_PATH}/actions/workflows/ci.yml/badge.svg )] ( https://github.com/{MODULE_PATH}/actions/workflows/ci.yml )
86[ ![ PowerShell Gallery] ( https://img.shields.io/powershellgallery/v/{MODULE_NAME}.svg )] ( https://www.powershellgallery.com/packages/{MODULE_NAME} )
97[ ![ Downloads] ( https://img.shields.io/powershellgallery/dt/{MODULE_NAME}.svg )] ( https://www.powershellgallery.com/packages/{MODULE_NAME} )
108[ ![ License] ( https://img.shields.io/github/license/{MODULE_PATH} )] ( LICENSE )
119
1210## 📂 Project Structure
1311
14- ```
12+ ``` plaintext
1513{MODULE_NAME}/
1614├── 📄 {MODULE_NAME}.build.ps1 # Invoke-Build script with all build tasks
1715├── 📄 requirements.psd1 # PSDepend configuration for dependencies
5149### Quick Start
5250
53511 . ** Clone or use this template:**
52+
5453 ``` bash
5554 git clone https://github.com/{MODULE_PATH}.git {MODULE_NAME}
5655 cd {MODULE_NAME}
5756 ```
5857
59- 2 . ** Install dependencies:**
58+ 1 . ** Install dependencies:**
59+
6060 ``` powershell
6161 # Install PSDepend if not already installed
6262 Install-Module -Name PSDepend -Scope CurrentUser -Force
6565 Invoke-PSDepend -Path ./requirements.psd1 -Install -Import -Force
6666 ```
6767
68- 3 . ** Build and test:**
68+ 1 . ** Build and test:**
69+
6970 ``` powershell
7071 # Run default build (Clean + Build)
7172 Invoke-Build
@@ -123,6 +124,7 @@ Invoke-Pester -Configuration @{
123124### Test Output
124125
125126All test results are saved to ` test-results/ ` directory:
127+
126128- ` unit-tests.xml ` - Pester test results (NUnit XML)
127129- ` code-coverage.xml ` - Code coverage report (Cobertura)
128130- ` static-code-analysis.xml ` - PSScriptAnalyzer results
@@ -138,8 +140,9 @@ Invoke-Build Export-CommandHelp
138140```
139141
140142Help files are generated in two formats:
143+
1411441 . ** Markdown** (` .md ` ) - Stored in ` docs/help/ ` for web/GitHub viewing
142- 2 . ** MAML** (` .xml ` ) - Stored in module's ` en-US/ ` folder for ` Get-Help ` command
145+ 1 . ** MAML** (` .xml ` ) - Stored in module's ` en-US/ ` folder for ` Get-Help ` command
143146
144147### Using Help in PowerShell
145148
@@ -162,11 +165,11 @@ The template includes a comprehensive CI/CD pipeline that runs automatically on
162165The CI workflow orchestrates multiple jobs in parallel:
163166
1641671 . ** Setup** - Caches PowerShell module dependencies for faster builds
165- 2 . ** Unit Tests** - Runs Pester tests with code coverage reporting
166- 3 . ** Static Code Analysis** - Validates code with PSScriptAnalyzer rules
167- 4 . ** Code Injection Analysis** - Scans for injection vulnerabilities with InjectionHunter
168- 5 . ** Semantic Code Analysis** - Runs CodeQL security analysis
169- 6 . ** Build** - Compiles module, generates help, creates releases, and publishes to PowerShell Gallery
168+ 1 . ** Unit Tests** - Runs Pester tests with code coverage reporting
169+ 1 . ** Static Code Analysis** - Validates code with PSScriptAnalyzer rules
170+ 1 . ** Code Injection Analysis** - Scans for injection vulnerabilities with InjectionHunter
171+ 1 . ** Semantic Code Analysis** - Runs CodeQL security analysis
172+ 1 . ** Build** - Compiles module, generates help, creates releases, and publishes to PowerShell Gallery
170173
171174### Workflow Triggers
172175
@@ -180,7 +183,7 @@ The CI workflow orchestrates multiple jobs in parallel:
180183The pipeline automatically determines the build type:
181184
182185| Event | Build Type | Version Format | Published |
183- | ------- | ----------- | ---------------- | ----------- |
186+ | ----- | ---------- | -------------- | --------- |
184187| Pull Request | Debug | ` 1.2.3-PullRequest1234 ` | No |
185188| Push to main | Prerelease | ` 1.2.3-Prerelease ` | Yes |
186189| Manual (workflow_dispatch) | Release | ` 1.2.3 ` | Optional |
@@ -200,7 +203,7 @@ This template uses **Semantic Versioning** (SemVer) with automated version manag
200203Include one of these keywords in your commit message:
201204
202205| Keyword | Version Change | Example |
203- | --------- | ---------------- | --------- |
206+ | ------- | -------------- | ------- |
204207| ` +semver: breaking ` or ` +semver: major ` | Major (1.0.0 → 2.0.0) | Breaking changes |
205208| ` +semver: feature ` or ` +semver: minor ` | Minor (1.0.0 → 1.1.0) | New features |
206209| ` +semver: fix ` or ` +semver: patch ` | Patch (1.0.0 → 1.0.1) | Bug fixes |
@@ -220,6 +223,7 @@ git commit -m "Update README +semver: none"
220223### Creating New Functions
221224
2222251 . ** Create function file** in ` src/Public/ ` or ` src/Private/ ` :
226+
223227 ``` powershell
224228 # src/Public/Get-Something.ps1
225229 function Get-Something {
@@ -247,7 +251,8 @@ git commit -m "Update README +semver: none"
247251 }
248252 ```
249253
250- 2 . ** Create test file** alongside function:
254+ 1 . ** Create test file** alongside function:
255+
251256 ``` powershell
252257 # src/Public/Get-Something.Tests.ps1
253258 BeforeAll {
@@ -262,25 +267,27 @@ git commit -m "Update README +semver: none"
262267 }
263268 ```
264269
265- 3 . ** Update module manifest** if adding public function:
270+ 1 . ** Update module manifest** if adding public function:
271+
266272 ``` powershell
267273 # Add to FunctionsToExport in PSScriptModule.psd1
268274 FunctionsToExport = @('Get-PSScriptModuleInfo', 'Get-Something')
269275 ```
270276
271- 4 . ** Build and test** :
277+ 1 . ** Build and test** :
278+
272279 ``` powershell
273280 Invoke-Build Test
274281 ```
275282
276283### Making Changes
277284
2782851 . Create feature branch: ` git checkout -b feature/my-feature `
279- 2 . Make your changes
280- 3 . Run tests: ` Invoke-Build Test `
281- 4 . Commit with semver keyword: ` git commit -m "Add feature +semver: minor" `
282- 5 . Push and create Pull Request
283- 6 . After PR merge, automatic release is triggered
286+ 1 . Make your changes
287+ 1 . Run tests: ` Invoke-Build Test `
288+ 1 . Commit with semver keyword: ` git commit -m "Add feature +semver: minor" `
289+ 1 . Push and create Pull Request
290+ 1 . After PR merge, automatic release is triggered
284291
285292## 📦 Publishing to PowerShell Gallery
286293
@@ -293,6 +300,7 @@ Invoke-Build -ReleaseType Release -NugetApiKey 'YOUR-API-KEY'
293300### Automated Publishing (CI/CD)
294301
295302Configure your GitHub repository secrets:
303+
296304- ` NUGETAPIKEY_PSGALLERY ` - Your PowerShell Gallery API key
297305
298306The CI/CD pipeline will automatically publish on release.
@@ -302,19 +310,21 @@ The CI/CD pipeline will automatically publish on release.
302310You can manually trigger builds and releases via GitHub Actions workflow dispatch:
303311
3043121 . ** Navigate to Actions** → CI workflow
305- 2 . ** Click "Run workflow"**
306- 3 . ** Configure options** :
313+ 1 . ** Click "Run workflow"**
314+ 1 . ** Configure options** :
307315 - ` version-tag ` : Specify a version tag to build (e.g., ` v0.9.7 ` ) - leave empty to use current commit
308316 - ` publish ` : Check to publish the release to PowerShell Gallery
309317
310318This is useful for:
319+
311320- Creating releases from specific commits or tags
312321- Re-publishing existing versions
313322- Testing release workflows before merging to main
314323
315324## 🤝 Contributing
316325
317326We welcome contributions! Please see our [ CONTRIBUTING.md] ( CONTRIBUTING.md ) guide for:
327+
318328- How to report issues
319329- Pull request process
320330- Code style guidelines
@@ -323,6 +333,7 @@ We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) guid
323333## 🤖 AI Agent Support
324334
325335This repository includes special documentation for AI coding assistants. See [ AGENTS.md] ( AGENTS.md ) for:
336+
326337- Project structure and conventions
327338- Function templates and patterns
328339- Testing guidelines
@@ -333,7 +344,7 @@ This repository includes special documentation for AI coding assistants. See [AG
333344This template uses the following PowerShell modules:
334345
335346| Module | Version | Purpose |
336- | -------- | --------- | --------- |
347+ | ------ | ------- | ------- |
337348| ** InvokeBuild** | 5.14.22 | Build orchestration |
338349| ** ModuleBuilder** | 3.1.8 | Module compilation |
339350| ** Pester** | 5.7.1 | Testing framework |
@@ -347,59 +358,6 @@ All dependencies are managed through `requirements.psd1` and can be installed wi
347358
348359This project is licensed under the terms specified in the [ LICENSE] ( LICENSE ) file.
349360
350- ## 🌟 Features in Detail
351-
352- ### PSScriptAnalyzer Integration
353-
354- Enforces PowerShell best practices and catches common mistakes:
355- - Cmdlet design rules
356- - Performance optimizations
357- - Security best practices
358- - Custom rule configurations via ` PSScriptAnalyzerSettings.psd1 `
359-
360- ### InjectionHunter Security
361-
362- Scans for common injection vulnerabilities:
363- - Command injection risks
364- - Script injection patterns
365- - Unsafe variable usage
366- - SQL injection patterns (if applicable)
367-
368- ### ModuleBuilder
369-
370- Compiles your script module:
371- - Combines all ` .ps1 ` files into single ` .psm1 `
372- - Updates module version automatically
373- - Copies required files to output
374- - Optimizes module loading
375-
376- ### PlatyPS Documentation
377-
378- Generates professional documentation:
379- - Markdown help files for each command
380- - MAML files for PowerShell's Get-Help
381- - Module-level documentation
382- - Example sections for usage
383-
384- ### CodeQL Semantic Analysis
385-
386- Advanced security scanning with GitHub CodeQL:
387- - Runs weekly on a schedule
388- - Integrates with GitHub Security tab
389- - Detects complex security vulnerabilities
390- - Provides actionable security insights
391-
392- ### Automated Maintenance Workflows
393-
394- Keep your repository clean with automated maintenance:
395- - ** Artifact Cleanup** : Automatically removes artifacts older than 2 days (configurable)
396- - ** Workflow Run Cleanup** : Removes old workflow runs to keep history manageable
397- - Configurable retention period (default: 2 days)
398- - Configurable minimum runs to keep (default: 2)
399- - Separate cleanup for pull requests, pushes, and scheduled runs
400- - Runs daily at midnight via cron schedule
401- - Can be triggered manually with custom parameters
402-
403361## 🎓 Learning Resources
404362
405363- [ PowerShell Best Practices] ( https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/cmdlet-development-guidelines )
@@ -411,9 +369,9 @@ Keep your repository clean with automated maintenance:
411369## 🆘 Support
412370
413371- 📖 Check the [ CONTRIBUTING.md] ( CONTRIBUTING.md ) guide
414- - 🐛 [ Report issues] ( https://github.com/WarehouseFinds/PSScriptModule.Template /issues )
415- - 💬 [ Start a discussion] ( https://github.com/WarehouseFinds/PSScriptModule.Template /discussions )
372+ - 🐛 [ Report issues] ( https://github.com/{MODULE_PATH} /issues )
373+ - 💬 [ Start a discussion] ( https://github.com/{MODULE_PATH} /discussions )
416374
417375---
418376
419- ** Built with ❤️ by [ Warehouse Finds] ( https://github.com/WarehouseFinds ) **
377+ ** Built with ❤️ by [ Warehouse Finds] ( https://github.com/WarehouseFinds ) **
0 commit comments