Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (111 loc) · 5.3 KB

CONTRIBUTING.md

File metadata and controls

150 lines (111 loc) · 5.3 KB

Contributing to Winrift

Thanks for your interest in contributing to Winrift! This guide will help you get started.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/winrift.git
  3. Create a branch for your changes: 
    git checkout -b feature/your-feature-name

Development Setup

Winrift is a PowerShell-based project. You'll need:

  • Windows 11 (for testing) — Download Windows 11 ISO
  • PowerShell 5.1+ (included with Windows)
  • A code editor (VS Code recommended with the PowerShell extension)
  • Recommended: PSScriptAnalyzer for linting

Setting up PSScriptAnalyzer

Install PSScriptAnalyzer to catch common PowerShell issues before submitting:

Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force

Run it against your changes:

# Analyze a single file
Invoke-ScriptAnalyzer -Path .\modules\system\Tweaks.ps1

# Analyze the entire project
Invoke-ScriptAnalyzer -Path . -Recurse

# Show only errors and warnings
Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning

Testing on a VM (Recommended)

Testing tweaks on a live system can cause irreversible changes. Use a Windows 11 VM instead:

  1. Download the Windows 11 ISO from Microsoft
  2. Create a VM in VirtualBox (free) or Hyper-V (built into Windows Pro/Enterprise)
  3. Install Windows 11, then snapshot the VM before testing tweaks
  4. Restore the snapshot between test runs to start clean

Project Structure

winrift/
├── Winrift.ps1          # Main entry point
├── version.json            # Version metadata
├── scripts/                # Core scripts (admin launch, common utilities)
├── modules/
│   ├── system/             # System tweaks
│   ├── security/           # Security tools
│   ├── drivers/            # Driver installation
│   ├── tools/              # Third-party tool integrations
│   ├── unigetui/           # Package manager integration
│   └── customize/          # Desktop environment, themes, configs
├── docs/                   # Documentation and guides
└── media/                  # Icons, logos, assets

Coding Guidelines

PowerShell Conventions

  • Use approved PowerShell verbs for function names (Get-, Set-, New-, Remove-, Invoke-, etc.)
  • Use 4-space indentation (no tabs)
  • Include error handling (try/catch) for any external downloads or network operations
  • Add descriptive -Message parameters to Set-RegistryValue calls
  • Use Write-Log (from scripts/Common.ps1) instead of bare Write-Host for user feedback

Adding New Tweaks

  1. Add your tweak function to the appropriate file in modules/
  2. Include source links as comments above registry modifications
  3. Test thoroughly on a clean Windows 11 installation
  4. Document what the tweak does and why

Template for a new tweak function:

function Invoke-MyNewTweak {
    # Source: https://example.com/source-of-this-tweak
    # What it does: Brief description of the effect on the system
    Write-Log -Message "Applying My New Tweak..." -Level INFO -LogFile $script:LogFile

    try {
        Set-RegistryValue -Path "HKCU:\Software\Example" `
                          -Name "SettingName" `
                          -Value 1 `
                          -Type DWord `
                          -Description "Enables example behavior"

        Write-Log -Message "My New Tweak applied successfully." -Level SUCCESS -LogFile $script:LogFile
    } catch {
        Write-Log -Message "Failed to apply My New Tweak: $($_.Exception.Message)" -Level ERROR -LogFile $script:LogFile
    }
}

Then register it in the tweak map inside Invoke-UniversalTweaks in modules/system/Tweaks.Universal.ps1.

Commit Messages

Write clear, concise commit messages:

  • fix: correct menu navigation for Security option
  • feat: add selective tweak application
  • docs: update README with compatibility table

Testing

Before submitting a PR:

  1. Test your changes on a clean Windows 11 VM (recommended) — see VM setup above
  2. Create a System Restore Point before testing tweaks
  3. Verify the menu navigation works correctly
  4. Check that all function names use approved PowerShell verbs
  5. Ensure no tabs are mixed with spaces
  6. Run PSScriptAnalyzer and fix any errors or warnings

Submitting a Pull Request

  1. Push your branch to your fork
  2. Open a Pull Request against the main branch
  3. Describe what your changes do and why
  4. Reference any related issues (e.g., "Fixes #42")

Reporting Issues

Use the issue templates provided:

  • Bug Report — for something that isn't working correctly
  • Feature Request — for suggesting new features or improvements

Code of Conduct

Be respectful and constructive. We're all here to make Windows 11 better.