Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (45 loc) · 2.34 KB

CONTRIBUTING.md

File metadata and controls

67 lines (45 loc) · 2.34 KB

Contributing

Development Standards

Code Quality

  • Follow PowerShell best practices for error handling, logging, and documentation
  • All code must execute with $ErrorActionPreference = 'Stop' and $PSNativeCommandUseErrorActionPreference = $true
  • Use Write-Debug for debug information ($DebugPreference = 'Continue' to enable)
  • Use Write-Warning for important warnings

Error Handling

  • Always use Assert-DeviceSession before device operations
  • Use consistent error messages: "No active device session" for session validation failures
  • Mark unimplemented features with # TODO: Implement <functionality>

Session Management

  • Only one device session active at a time
  • Auto-disconnect when connecting to a new platform
  • All functions must validate session before executing

Testing

Run tests before committing (needs to run in a new shell to avoid caching the module):

# Run all tests (device tests automatically skip if SDKs not available)
pwsh -c 'Invoke-Pester -Path ./app-runner/Tests/ -Output Detailed'

# Run only unit tests (excluding device integration tests)
pwsh -c 'Invoke-Pester -Path ./app-runner/Tests/ -ExcludeTag "RequiresDevice" -Output Detailed'

# Run device tests for specific platform (requires SDK installed)
pwsh -c 'Invoke-Pester -Path ./app-runner/Tests/Device.Tests.ps1 -TagFilter "Xbox" -Output Detailed'

Device Integration Tests

Device integration tests (Device.Tests.ps1) automatically detect SDK availability:

  • Xbox: Requires $env:GameDK set or xbconnect.exe in PATH
  • PlayStation5: Requires $env:SCE_ROOT_DIR set or prospero-ctrl.exe in PATH
  • Switch: Requires $env:NINTENDO_SDK_ROOT set or ControlTarget.exe in PATH

If no SDKs are detected, device tests are automatically skipped with a warning. This allows:

  • CI to run without platform SDKs installed
  • Developers to run tests locally with only the SDKs they have access to
  • Full platform coverage when all SDKs are available

All tests must pass before committing.

Code Analysis

# Run PSScriptAnalyzer
Invoke-ScriptAnalyzer -Path ./app-runner -Recurse -Settings ./PSScriptAnalyzerSettings.psd1

Pull Requests

  • Keep changes focused and small
  • Include tests for new functionality
  • Ensure CI passes (unit tests, integration tests, PSScriptAnalyzer)
  • Update documentation if needed