mirror of
https://github.com/GoodOlClint/PSProxmoxVE.git
synced 2026-09-03 18:55:33 +00:00
goodolclint-claude[bot]
fc073e7e2a
Pester was installed with -MinimumVersion 5.0 and no ceiling in the CI job image, both install steps in unit-tests.yml, and both Import-Module calls, plus the suite's own import inside the container. The image is rebuilt on every CI run and Pester is installed fresh on every unit-test run, so PSGallery chose the version — a new major could reach the required PR checks with no commit here, surfacing as unexplained test breakage on whichever PR ran next. It had already happened. Steps named "Install Pester 5" were resolving 6.1.0 on both legs, because Pester 6 declares PowerShellVersion 5.1 and so installs on Windows PowerShell too. Nothing broke — the suite uses only constructs common to 5 and 6, and runs 1566/0 under 6.1.0 with no deprecation warnings — but nobody chose it. The step names are corrected; they had been describing an install that stopped happening some time ago. Pinning the install alone is not enough, in two ways review found: An unset variable does not fail. -RequiredVersion accepts an empty value and degrades to "latest" for Install-Module and to "any" for Import-Module, both exiting 0, so a renamed or dropped env key would silently restore the float this commit removes. A guard step now fails the job instead. The point of use was still floored. run-integration.sh imported the suite's Pester with -MinimumVersion 5.0, so a second Pester reaching PSModulePath would win regardless of what was installed. The Dockerfile now promotes the ARG to ENV so the version is discoverable at runtime, and that import is pinned to it. The pin lives in two files, so shell-selfchecks asserts they agree — split-brain between the workflow and the image is precisely the unexplained breakage this is meant to prevent. CONTRIBUTING.md and CLAUDE.md are updated too; the contributor instructions were a third floating install site. Recorded as an amendment to D017 — the same principle as the nested PVE package pin, applied to the lane's own tooling.
98 lines
3.7 KiB
Markdown
98 lines
3.7 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](https://pester.dev/) — match CI's pin: `Install-Module Pester -RequiredVersion 6.1.0 -Force`
|
|
(the version is `PESTER_VERSION` in `.github/workflows/unit-tests.yml`)
|
|
- 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).
|