Contributing

Welcome to the comprehensive contributing guide for PIMActivation. This document provides detailed technical information for developers.

Table of Contents

• Development Environment Setup
• Project Structure
• Coding Standards
• Testing Guidelines
• Pull Request Process
• Release Process
• AI-Assisted Development

🛠️ Development Environment Setup

Prerequisites

• Windows 10/11 or Windows Server 2016+
• PowerShell 7+ (Download)
• Visual Studio Code with PowerShell extension (recommended)
• Git for version control
• GitHub account

Initial Setup

# Fork and clone the repository
git clone https://github.com/Noble-Effeciency13/PIMActivation.git
cd PIMActivation

# Create development branch
git checkout -b feature/your-feature-name

# Install development dependencies
Install-Module -Name Pester -Scope CurrentUser -Force
Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force
Install-Module -Name platyPS -Scope CurrentUser -Force
Install-Module -Name Az.Accounts -Scope CurrentUser -Force

# Import module for development
Import-Module .\PIMActivation.psd1 -Force

# Verify setup
$PSVersionTable.PSVersion  # Should be 7.0 or higher
Get-Module PIMActivation

Recommended VS Code Extensions

• PowerShell (ms-vscode.powershell)
• GitLens (eamodio.gitlens)
• Markdown All in One (yzhang.markdown-all-in-one)
• Todo Tree (Gruntfuggly.todo-tree)

📁 Project Structure

PIMActivation/
├── PIMActivation.psd1          # Module manifest
├── PIMActivation.psm1          # Root module
├── Public/                     # Exported functions
│   └── Start-PIMActivation.ps1 # Main entry point
├── Private/                    # Internal functions
│   ├── Authentication/         # Auth handling
│   ├── RoleManagement/        # PIM role operations
│   ├── UI/                    # GUI components
│   ├── Utilities/             # Helper functions
│   └── Profiles/              # User profiles
├── docs/                      # Documentation
├── Tests/                     # Pester tests
├── Resources/                 # Icons, images
└── .github/                   # GitHub specific files

Adding New Features

1. Determine Function Placement

• Public functions → Public/ directory (will be exported)
• Private functions → Private/[Category]/ directory (internal use)

2. Function Template

function New-PIMFeature {
    <#
    .SYNOPSIS
        Brief description (one line)
    
    .DESCRIPTION
        Detailed description of what the function does,
        why it exists, and when to use it.
    
    .PARAMETER ParameterName
        Description of the parameter
    
    .EXAMPLE
        New-PIMFeature -ParameterName "Value"
        
        Description of what this example does
    
    .NOTES
        Author: Your Name
        Date: Current Date
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, HelpMessage = "Helpful message")]
        [ValidateNotNullOrEmpty()]
        [string]$ParameterName
    )
    
    begin {
        Write-Verbose "Starting $($MyInvocation.MyCommand.Name)"
    }
    
    process {
        try {
            # Implementation
        }
        catch {
            Write-Error "Failed to execute feature: $_"
            throw
        }
    }
    
    end {
        Write-Verbose "Completed $($MyInvocation.MyCommand.Name)"
    }
}

📝 Coding Standards

PowerShell Best Practices

1. Cmdlet Naming

   • Use approved verbs: Get-Verb | Sort-Object Verb
   • Follow Noun-Verb pattern: Verb-PIMNoun

2. Parameter Guidelines

   • Use parameter validation attributes
   • Provide helpful parameter descriptions
   • Include parameter help messages

3. Error Handling

   try {
       # Risky operation
   }
   catch [System.Net.WebException] {
       Write-Error "Network error: $_" -ErrorAction Continue
   }
   catch {
       Write-Error "Unexpected error: $_"
       throw
   }

4. Output and Verbosity

   • Use Write-Verbose for debug information
   • Use Write-Warning for important notices
   • Use Write-Error for errors (not Write-Host)
   • Return objects, not formatted text

Code Style Guidelines

• Indentation: 4 spaces (not tabs)
• Brace Style: Opening brace on same line
• Line Length: Max 120 characters
• Comments: Above the code, not beside
• Variable Names: PascalCase for parameters, camelCase for variables

UI Development Standards

# Control naming convention
$btnActivate     # Button prefix: btn
$txtJustification # TextBox prefix: txt
$lblStatus       # Label prefix: lbl
$chkSelectAll    # CheckBox prefix: chk
$lstRoles        # ListBox prefix: lst

# Event handler naming
$btnActivate.Add_Click({...})  # Add_EventName

🧪 Testing Guidelines

Unit Test Structure

Create test file: Tests/Unit/FunctionName.Tests.ps1

BeforeAll {
    # Load the module
    $ModulePath = "$PSScriptRoot\..\..\PIMActivation.psd1"
    Import-Module $ModulePath -Force
    
    # Mock external dependencies
    Mock Connect-MgGraph { }
}

Describe 'New-PIMFeature' {
    Context 'Parameter Validation' {
        It 'Should require mandatory parameters' {
            { New-PIMFeature } | Should -Throw
        }
        
        It 'Should validate parameter types' {
            { New-PIMFeature -ParameterName 123 } | Should -Throw
        }
    }
    
    Context 'Core Functionality' {
        BeforeEach {
            # Setup for each test
        }
        
        It 'Should return expected results' {
            $result = New-PIMFeature -ParameterName "Test"
            $result | Should -Not -BeNullOrEmpty
            $result.Property | Should -Be "ExpectedValue"
        }
        
        It 'Should handle errors gracefully' {
            Mock Some-Dependency { throw "Error" }
            { New-PIMFeature -ParameterName "Test" } | Should -Throw
        }
    }
}

AfterAll {
    # Cleanup
    Remove-Module PIMActivation -Force
}

Integration Test Template

Describe 'PIM Integration Tests' -Tag 'Integration' {
    BeforeAll {
        # Requires actual connection
        Connect-MgGraph -Scopes "RoleAssignmentSchedule.ReadWrite.Directory"
    }
    
    It 'Should activate a role successfully' {
        # Integration test with real API
    }
}

Running Tests

# Run all tests
Invoke-Pester -Path .\Tests

# Run specific test file
Invoke-Pester -Path .\Tests\Unit\New-PIMFeature.Tests.ps1

# Run with code coverage
Invoke-Pester -CodeCoverage .\Public\*, .\Private\*

# Run only unit tests
Invoke-Pester -Tag Unit

🔄 Pull Request Process

Before Creating a PR

1. Update your fork

   git checkout main
   git pull upstream main
   git checkout feature/your-feature
   git rebase main

2. Run quality checks

   # PSScriptAnalyzer
   Invoke-ScriptAnalyzer -Path . -Recurse -ExcludeRule PSUseSingularNouns
   
   # Tests
   Invoke-Pester -Path .\Tests
   
   # Module manifest
   Test-ModuleManifest -Path .\PIMActivation.psd1

3. Update documentation

   • Update README.md if adding user-facing features
   • Update CHANGELOG.md with your changes
   • Add/update help documentation
   • Update wiki if needed

PR Checklist

• Code follows PowerShell best practices
• All tests pass
• Documentation updated
• CHANGELOG.md updated
• No sensitive information included
• Tested on PowerShell 7+
• PSScriptAnalyzer passes
• Commits are logical and well-described

PR Title Format

Use conventional commit format:

• feat: add bulk deactivation support
• fix: handle authentication timeout correctly
• docs: update installation instructions
• refactor: simplify role enumeration logic
• test: add unit tests for role activation
• chore: update dependencies

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Tested on PowerShell 7+

## AI Assistance
- [ ] No AI assistance used
- [ ] AI used for: [describe what parts]

## Screenshots (if applicable)
Add screenshots for UI changes

📦 Release Process

Version Numbering

Follow Semantic Versioning:

• MAJOR.MINOR.PATCH (e.g., 1.2.3)
• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

Release Checklist

1. Update version

   Update-ModuleManifest -Path PIMActivation.psd1 -ModuleVersion "1.1.0"

2. Update CHANGELOG.md

   • Add new version section
   • List all changes
   • Credit contributors

3. Update documentation

   • README.md if needed
   • Wiki pages
   • Help documentation

4. Create release branch

   git checkout -b release/v1.1.0
   git push origin release/v1.1.0

5. Tag release

   git tag -a v1.1.0 -m "Release version 1.1.0"
   git push origin v1.1.0

🤖 AI-Assisted Development

This project embraces modern development practices including AI-assisted programming.

When to Use AI

✅ Good Use Cases:

• Generating boilerplate code
• Writing comprehensive documentation
• Creating test cases
• Suggesting error handling patterns
• Refactoring for readability

❌ Avoid AI For:

• Security-sensitive code without review
• Complex business logic without understanding
• Copy-pasting without comprehension

Guidelines

1. Always review and understand AI-generated code
2. Test thoroughly - AI can make subtle mistakes
3. Security review - Check for vulnerabilities
4. Maintain consistency - Ensure AI code matches project style
5. Document AI usage in PR descriptions

Example PR with AI Attribution

This PR adds support for bulk role deactivation.

## Changes
- Added `Invoke-BulkDeactivation` function
- Updated UI with deactivation options
- Added progress tracking

## AI Assistance
- GitHub Copilot used for:
  - Initial function structure
  - Error handling patterns
  - Test case generation
- All code reviewed and tested manually

🏷️ Issue Labels

Priority Labels

• priority-critical: Security issues, data loss
• priority-high: Major functionality broken
• priority-medium: Important but not urgent
• priority-low: Nice to have

Type Labels

• bug: Something isn't working
• enhancement: New feature or request
• documentation: Documentation improvements
• performance: Performance improvements
• refactor: Code improvement without functionality change

Status Labels

• help-wanted: Community help needed
• good-first-issue: Good for newcomers
• blocked: Waiting on something
• in-progress: Currently being worked on

📚 Additional Resources

• PowerShell Best Practices
• Git Commit Guidelines
• Semantic Versioning
• Microsoft Graph API Documentation
• PIM API Reference

❓ Getting Help

• 💬 GitHub Discussions - Community Q&A
• 🐛 GitHub Issues - Bug reports
• 📖 Project Wiki - Documentation
• 📝 Blog Post - Detailed walkthrough

---

Thank you for contributing to PIMActivation! Your efforts help make PIM management better for the entire community. 🎉