mirror of
https://github.com/GoodOlClint/PSProxmoxVE.git
synced 2026-07-26 07:58:14 +00:00
Clint Branham
89bead7a0e
Restart-PveContainer gained ConfirmImpact.High in the F062 fix, which correctly prompts for confirmation on destructive operations. The integration test was missing -Confirm:$false, causing a NullReferenceException in non-interactive CI. The cascading failure also broke the Copy-PveContainer test (F081). Also updates CONTRIBUTING.md to reference .NET SDK 10.0+ (was 9.0+) to match all CI workflows and test project TFM (F083). Includes scan-6 review report and findings database update (F001-F083). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
# 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 10.0+](https://dotnet.microsoft.com/download)
|
|
- [PowerShell 7.2+](https://github.com/PowerShell/PowerShell) (for running Pester tests)
|
|
- [Pester 5](https://pester.dev/) (`Install-Module Pester -MinimumVersion 5.0 -Force`)
|
|
- An IDE with C# support (Visual Studio, VS Code with C# Dev Kit, Rider)
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://www.conventionalcommits.org/):
|
|
|
|
- `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](https://github.com/goodolclint/PSProxmoxVE/issues) for bug reports and feature requests.
|
|
- For security vulnerabilities, see [SECURITY.md](SECURITY.md).
|