Merge pull request #110 from WarehouseFinds/feat/documentation_update

Add Code of Conduct, update documentation, and enhance CI/CD pipeline details

Author: marko-stanojevic

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to PSScriptModule.Template
+# Contributing to PSScriptModule
 
-Thank you for your interest in contributing to PSScriptModule.Template! This document provides guidelines and instructions for contributing to this project.
+Thank you for your interest in contributing to PSScriptModule! This document provides guidelines and instructions for contributing to this project.
 
 ## Code of Conduct
 

README.md

@@ -0,0 +1,23 @@
+# 🔧 Build Tasks
+
+The template includes several pre-configured build tasks:
+
+```powershell
+# Clean + Build (default)
+Invoke-Build
+
+# Individual tasks
+Invoke-Build Clean                    # Remove build artifacts
+Invoke-Build Build                    # Build the module
+Invoke-Build Test                     # Run all tests
+Invoke-Build Invoke-PSScriptAnalyzer  # Run static code analysis
+Invoke-Build Invoke-InjectionHunter   # Run security scans
+Invoke-Build Invoke-UnitTests         # Run Pester tests with coverage
+Invoke-Build Export-CommandHelp       # Generate documentation
+Invoke-Build Publish                  # Publish to PowerShell Gallery
+
+# Build for different configurations
+Invoke-Build -ReleaseType Debug       # Development build
+Invoke-Build -ReleaseType Release     # Production build
+Invoke-Build -ReleaseType Prerelease  # Pre-release build
+```

docs/building.md

@@ -0,0 +1,61 @@
+# 🔄 CI/CD Pipeline
+
+The template includes a comprehensive CI/CD pipeline that runs automatically on pull requests and pushes to main.
+
+## Pipeline Structure
+
+The CI workflow orchestrates multiple jobs in parallel:
+
+1. **Setup** - Caches PowerShell module dependencies for faster builds
+1. **Unit Tests** - Runs Pester tests with code coverage reporting
+1. **Static Code Analysis** - Validates code with PSScriptAnalyzer rules
+1. **Code Injection Analysis** - Scans for injection vulnerabilities with InjectionHunter
+1. **Semantic Code Analysis** - Runs CodeQL security analysis
+1. **Build** - Compiles module, generates help, creates releases, and publishes to PowerShell Gallery
+
+### Workflow Triggers
+
+- **Pull Request**: Runs all quality gates (tests not run for workflow-only changes)
+- **Push to main**: Runs full pipeline and creates prerelease
+- **Workflow Dispatch**: Manual trigger with custom version and publish options
+- **Schedule**: Weekly CodeQL security scan
+
+## Build Types
+
+The pipeline automatically determines the build type:
+
+| Event | Build Type | Version Format | Published |
+| --------- | ---------------- | --------- |
+| Pull Request | Debug | `1.2.3-PullRequest1234` | No |
+| Push to main | Prerelease | `1.2.3-Prerelease` | Yes |
+| Manual (workflow_dispatch) | Release | `1.2.3` | Optional |
+
+## 🔄 Versioning Strategy
+
+This template uses **Semantic Versioning** (SemVer) with automated version management through GitVersion.
+
+### GitVersion Configuration
+
+- **Workflow**: GitHub Flow (main branch + feature branches)
+- **Strategy**: Every PR merge to `main` creates a new release
+- **Version calculation**: Based on commit history and tags
+
+### Controlling Version Bumps
+
+Include one of these keywords in your commit message:
+
+| Keyword | Version Change | Example |
+| --------- | ---------------- | --------- |
+| `+semver: breaking` or `+semver: major` | Major (1.0.0 → 2.0.0) | Breaking changes |
+| `+semver: feature` or `+semver: minor` | Minor (1.0.0 → 1.1.0) | New features |
+| `+semver: fix` or `+semver: patch` | Patch (1.0.0 → 1.0.1) | Bug fixes |
+| `+semver: none` or `+semver: skip` | No change | Documentation updates |
+
+### Example Commit Messages
+
+```bash
+git commit -m "Add new Get-Something function +semver: minor"
+git commit -m "Fix parameter validation bug +semver: patch"
+git commit -m "Remove deprecated function +semver: breaking"
+git commit -m "Update README +semver: none"
+```

docs/ci-cd.md

@@ -0,0 +1,14 @@
+# 📋 Dependencies
+
+This template uses the following PowerShell modules:
+
+| Module | Version | Purpose |
+| --------- | ---------------- | --------- |
+| **InvokeBuild** | 5.14.22 | Build orchestration |
+| **ModuleBuilder** | 3.1.8 | Module compilation |
+| **Pester** | 5.7.1 | Testing framework |
+| **PSScriptAnalyzer** | 1.24.0 | Static code analysis |
+| **InjectionHunter** | 1.0.0 | Security vulnerability scanning |
+| **Microsoft.PowerShell.PlatyPS** | 1.0.1 | Help documentation generation |
+
+All dependencies are managed through `requirements.psd1` and can be installed with PSDepend.

docs/dependencies.md

@@ -0,0 +1,78 @@
+# 🛠️ Development Workflow
+
+## Creating New Functions
+
+1. **Create function file** in `src/Public/` or `src/Private/`:
+
+   ```powershell
+   # src/Public/Get-Something.ps1
+   function Get-Something {
+       <#
+       .SYNOPSIS
+           Brief description
+       
+       .DESCRIPTION
+           Detailed description
+       
+       .PARAMETER Name
+           Parameter description
+       
+       .EXAMPLE
+           Get-Something -Name 'Example'
+           Description of example
+       #>
+       [CmdletBinding()]
+       param (
+           [Parameter(Mandatory)]
+           [string]$Name
+       )
+       
+       # Implementation
+   }
+   ```
+
+1. **Create test file** alongside function:
+
+   ```powershell
+   # src/Public/Get-Something.Tests.ps1
+   BeforeAll {
+       . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
+   }
+   
+   Describe 'Get-Something' {
+       It 'Should return expected result' {
+           $result = Get-Something -Name 'test'
+           $result | Should -Not -BeNullOrEmpty
+       }
+   }
+   ```
+
+1. **Update module manifest** if adding public function:
+
+   ```powershell
+   # Add to FunctionsToExport in PSScriptModule.psd1
+   FunctionsToExport = @('Get-PSScriptModuleInfo', 'Get-Something')
+   ```
+
+1. **Build and test**:
+
+   ```powershell
+   Invoke-Build Test
+   ```
+
+### Making Changes
+
+1. Create feature branch: `git checkout -b feature/my-feature`
+1. Make your changes
+1. Run tests: `Invoke-Build Test`
+1. Commit with semver keyword: `git commit -m "Add feature +semver: minor"`
+1. Push and create Pull Request
+1. After PR merge, automatic release is triggered
+
+## 🎓 Learning Resources
+
+- [PowerShell Best Practices](https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/cmdlet-development-guidelines)
+- [Pester Documentation](https://pester.dev/)
+- [PSScriptAnalyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer)
+- [Semantic Versioning](https://semver.org/)
+- [GitHub Flow](https://guides.github.com/introduction/flow/)

docs/development.md

@@ -0,0 +1,31 @@
+# Generating Help
+
+This project uses [PlatyPS](https://github.com/PowerShell/platyPS) to generate extensive documentation:
+
+- Markdown help files for each command
+- MAML files for PowerShell's Get-Help
+- Module-level documentation
+- Example sections for usage
+
+```powershell
+
+# Generate markdown and MAML help files
+Invoke-Build Export-CommandHelp
+```
+
+Help files are generated in two formats:
+
+1. **Markdown** (`.md`) - Stored in `docs/help/` for web/GitHub viewing
+1. **MAML** (`.xml`) - Stored in module's `en-US/` folder for `Get-Help` command
+
+## Using Help in PowerShell
+
+```powershell
+# Import your module
+Import-Module ./build/out/PSScriptModule/PSScriptModule.psd1
+
+# View help
+Get-Help Get-PSScriptModuleInfo -Full
+Get-Help Get-PSScriptModuleInfo -Examples
+Get-Help Get-PSScriptModuleInfo -Online
+```