PSProxmoxVE/CONTRIBUTING.md

Contributing to PSProxmoxVE

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to PSProxmoxVE.

Development Setup

Prerequisites

• .NET SDK 9.0+
• PowerShell 7.2+ (for running Pester tests)
• Pester 5 (Install-Module Pester -MinimumVersion 5.0 -Force)
• An IDE with C# support (Visual Studio, VS Code with C# Dev Kit, Rider)

Building

# Clone the repository
git clone https://github.com/goodolclint/PSProxmoxVE.git
cd PSProxmoxVE

# Restore and build
dotnet build

# Publish for local testing
dotnet publish src/PSProxmoxVE/PSProxmoxVE.csproj --framework netstandard2.0 --output ./publish/netstandard2.0

Running Tests

# xUnit unit tests (C# core library)
dotnet test tests/PSProxmoxVE.Core.Tests

# Pester cmdlet tests (requires built module)
pwsh -Command "Invoke-Pester -Path tests/PSProxmoxVE.Tests -ExcludeTag Integration"

# Integration tests (requires live PVE node -- see tests/infrastructure/README.md)
pwsh -Command "Invoke-Pester -Path tests/PSProxmoxVE.Tests/Integration -Tag Integration"

Coding Standards

C# Style

• Use C# 10.0 language features.
• Enable nullable reference types (#nullable enable).
• Follow standard .NET naming conventions (PascalCase for public members, camelCase for locals).
• Use 4-space indentation (see .editorconfig).

Cmdlet Design

• Verb-Noun naming: Use approved PowerShell verbs (Get-Verb to see the list). Noun prefix is always Pve.
• ShouldProcess: All mutating cmdlets must implement SupportsShouldProcess = true and call ShouldProcess().
• ConfirmImpact: Set ConfirmImpact.High on destructive operations (Remove, Stop, Reset).
• OutputType: Every cmdlet must have an [OutputType] attribute.
• Pipeline support: Use ValueFromPipelineByPropertyName = true on Node, VmId, and similar parameters.
• WriteVerbose: Add a WriteVerbose call describing the API operation before making API calls.
• HelpMessage: All [Parameter] attributes should include a HelpMessage.
• ValidateRange: VmId parameters should have [ValidateRange(100, 999999999)].

Commit Convention

This project uses Conventional Commits:

• feat: -- new feature
• fix: -- bug fix
• test: -- test additions or changes
• ci: -- CI/CD changes
• docs: -- documentation changes
• refactor: -- code refactoring
• chore: -- maintenance tasks

Pull Request Process

1. Fork the repository and create a feature branch from main.
2. Make your changes following the coding standards above.
3. Add or update tests for your changes.
4. Ensure dotnet build succeeds with zero warnings.
5. Ensure all existing tests pass.
6. Update CHANGELOG.md under [Unreleased] with a description of your change.
7. Submit a pull request with a clear description of the change and its motivation.

Adding a New Cmdlet

1. Create the cmdlet class in the appropriate Cmdlets/ subdirectory.
2. Create or extend a service class in PSProxmoxVE.Core/Services/.
3. Add model classes in PSProxmoxVE.Core/Models/ if needed.
4. Add the cmdlet name to CmdletsToExport in PSProxmoxVE.psd1.
5. Add Pester unit tests in tests/PSProxmoxVE.Tests/.
6. Add integration test coverage in Integration.Tests.ps1 if applicable.
7. Update README.md cmdlet reference table.

Reporting Issues

• Use GitHub Issues for bug reports and feature requests.
• For security vulnerabilities, see SECURITY.md.