Contributing to PowerNetbox

December 26, 2025 · View on GitHub

Thank you for your interest in contributing to PowerNetbox! This document explains our development practices and how to contribute effectively.

Code of Conduct
Getting Started
Development Workflow
Code Quality Standards
Testing Requirements
Pull Request Process
Why These Practices?

Code of Conduct

Be respectful, inclusive, and constructive. We're all here to build great software together.

Getting Started

Prerequisites

PowerShell 5.1+ (Desktop) or PowerShell 7+ (Core)
Git
A Netbox instance for testing (or use Docker)
Pester 5.0+ for running tests

Setup

# Clone the repository
git clone https://github.com/ctrl-alt-automate/PowerNetbox.git
cd PowerNetbox

# Build the module
./deploy.ps1 -Environment dev -SkipVersion

# Run tests
Invoke-Pester ./Tests/

Docker-based Testing

# Start a local Netbox instance
docker compose -f docker-compose.ci.yml up -d

# Wait for Netbox to be ready (2-3 minutes)
# Then run integration tests
pwsh -Command "Invoke-Pester ./Tests/Integration.Tests.ps1 -Tag 'Live'"

# Cleanup
docker compose -f docker-compose.ci.yml down -v

Development Workflow

Branch Strategy

Branch	Purpose
`main`	Production releases (published to PSGallery)
`dev`	Active development
`beta`	Pre-release testing (e.g., Netbox 4.5 compatibility)
`feature/*`	Feature branches
`fix/*`	Bug fix branches

Creating a Feature

Create a branch from dev:

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

Make your changes following our code standards
Test your changes:
```
Invoke-Pester ./Tests/
```

Commit with meaningful messages:

git commit -m "feat(dcim): Add support for cable profiles"

Push and create a PR against dev

Code Quality Standards

PowerShell Best Practices

We follow the PowerShell Practice and Style Guidelines.

Required Attributes

function Get-NBExample {
    [CmdletBinding()]                    # Always required
    [OutputType([PSCustomObject])]       # Document return type
    param (
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]       # Validate inputs
        [string]$Name,

        [switch]$Raw                     # All functions need -Raw switch
    )

    process {                            # Use process block for pipeline support
        # Implementation
    }
}

State-Changing Functions

Functions that modify data must use SupportsShouldProcess:

function New-NBExample {
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')]
    param(...)

    process {
        if ($PSCmdlet.ShouldProcess($Name, 'Create Example')) {
            # Create the resource
        }
    }
}

Verb	ConfirmImpact
New-	Low
Set-	Medium
Remove-	High

Naming Conventions

Functions: [Verb]-NB[Module][Resource] (e.g., Get-NBDCIMDevice)
Files: One function per file, filename matches function name
Parameters: PascalCase, use standard names (Id, Name, Limit, Offset)

Forbidden Practices

❌ Write-Host (use Write-Verbose instead)
❌ Hardcoded paths or credentials
❌ Using \ in paths (use Join-Path)
❌ Ignoring errors silently

Automated Checks

Every PR is automatically checked for:

Check	Tool	Purpose
Linting	PSScriptAnalyzer	PowerShell best practices
Unit Tests	Pester	Code correctness
Cross-Platform	GitHub Actions	Windows, Linux, macOS compatibility

Testing Requirements

Unit Tests

All new functions need corresponding tests
Tests go in Tests/ directory
Use Pester 5.x syntax

Describe "Get-NBDCIMDevice" {
    It "Should return devices" {
        # Test implementation
    }
}

Test Coverage

We aim for comprehensive coverage of:

Happy path scenarios
Error handling
Edge cases
Pipeline input

Running Tests

# All tests
Invoke-Pester ./Tests/

# Specific test file
Invoke-Pester ./Tests/DCIM.Tests.ps1

# With coverage
Invoke-Pester ./Tests/ -CodeCoverage ./Functions/**/*.ps1