Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
89 lines (59 loc) · 2.58 KB

CONTRIBUTING.md

File metadata and controls

89 lines (59 loc) · 2.58 KB
Raw

Contributing to pwsh-gitlab

Thanks for your interest in contributing! This document outlines how to set up your development environment and the tools we use.

Prerequisites

Required

Tool Version Installation
PowerShell 7.1+ brew install powershell (macOS)
just latest brew install just (macOS)

Optional

Tool Purpose
Docker Run the module in a container

Development Workflow

We use just as a task runner.

The default task is to run everything

just

Tooling

Testing — Pester

Tests are located in the tests/ directory. We use Pester v5+ for unit testing.

just test

Documentation — PlatyPS

Cmdlet documentation is generated from code comments using PlatyPS and published to GitHub Pages.

just help-update

Documentation lives in docs/.

Run just help-update after adding or renaming parameters — it syncs structural metadata (types, parameter sets, aliases) while preserving hand-written descriptions. CI enforces docs are in sync.

Changes not handled by PlatyPS may require manual updates to specific markdown files.

Security Analysis

We use two tools for security and code quality:

Tool Purpose When
PSScriptAnalyzer PowerShell linting & best practices Local + CI
CodeQL Security vulnerability scanning CI only 
just lint           # Run PSScriptAnalyzer locally
just lint-verbose   # Show detailed results

Configuration is in PSScriptAnalyzerSettings.ps1.

Making Changes

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Run just check to verify tests pass and no lint errors
  5. Run just help-update if you added/modified cmdlets
  6. Commit your changes
  7. Open a Pull Request

Code Style

  • Follow PowerShell Best Practices
  • Use approved verbs for cmdlet names (Get-Verb to see the list)
  • Add tests for new functionality
  • Avoid inline commenting (except when necessary); instead, prefer intention-revealing code. Often a well-named function removes the need for a comment.