Contributing & Development

Contributions are welcome to help maintain the framework. Please adhere to the guidelines below when modifying code or submitting changes.

Code of Conduct

Contributors must adhere to the standards of the Contributor Covenant Code of Conduct. Ensure communication remains respectful, inclusive, and professional in all community interactions.

Formatting and Linter Requirements

To ensure consistent formatting and clean commits, the project uses pre-commit hooks.

Setting Up Linting Hooks

Install the required tools locally before committing modifications to the repository:

# Install pre-commit tool
pip3 install pre-commit

# Configure hooks within your local git repository
pre-commit install
pre-commit install-hooks

The hooks process changes automatically during commit stages, checking for trailing whitespace, well-formed YAML structures, byte-order-marks (BOM), and proper format syntax. To trigger validation checks manually, use:

pre-commit run --all-files

PowerShell Quality Checks

The project uses PSScriptAnalyzer to validate PowerShell scripting formatting. The local analyzer rules are configured in PSScriptAnalyzerSettings.psd1:

@{
    # Explicit exclusions permitted for testing purposes
    ExcludeRules=@('PSUseSingularNouns',
                'PSAvoidUsingWriteHost')
}

Make sure your changes pass script analyzer checks locally before pushing your branch:

Install-Module -Name PSScriptAnalyzer -Force
Invoke-ScriptAnalyzer -Recurse ./ -Settings ./PSScriptAnalyzerSettings.psd1 -Fix

Testing Framework

Contributions that alter cmdlet behaviors must include tests written in the Pester testing framework. Test cases are maintained in the Tests/ directory of the repository.

Run the test suite locally before submitting a Pull Request to verify that existing functionality has not been altered:

# Install Pester dependency
Install-Module -Name Pester -Force

# Run local validation suite
Invoke-Pester -Path ./Tests/

Submitting Changes

  1. Fork the repository and create a descriptive branch name from master.
  2. Apply changes, run the code analyzers, and verify code coverage via Pester.
  3. Submit a Pull Request targeting the master branch. Provide an explanation of the change, including targeted problems or added features.

For details on test schema requirements, refer to Programmatic Test Authoring. For structural cmdlet variables, see API Reference.