Contributing to ColorScripts-Enhanced

Thank you for your interest in contributing to ColorScripts-Enhanced! This document provides guidelines for contributing to the project.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors. Please review the Code of Conduct before submitting contributions.

How to Contribute

Reporting Bugs

Check if the bug has already been reported in Issues
If not, create a new issue with:
- Clear, descriptive title
- Steps to reproduce
- Expected vs actual behavior
- PowerShell version ($PSVersionTable)
- Terminal information
- Error messages (if any)

Suggesting Features

Check if the feature has been suggested
Create a new issue with:
- Clear description of the feature
- Use cases and benefits
- Possible implementation approach
- Examples of similar features

Contributing Code

Adding New Colorscripts

Create the script file
- Place in ColorScripts-Enhanced/Scripts/
- Use lowercase-with-hyphens naming: my-cool-script.ps1
- Include proper UTF-8 encoding

Script structure

# Script Name - Brief description
# Your colorscript code here
Write-Host "Beautiful ANSI art" -ForegroundColor Green

Follow guidelines
- Use ANSI escape codes for colors: $esc = [char]27
- Support UTF-8 encoding
- Keep scripts under 500 lines when possible
- Add comments for complex sections
- Test on multiple terminals

Test your script

# Test direct execution
& .\ColorScripts-Enhanced\Scripts\my-cool-script.ps1

# Test via module
Show-ColorScript -Name my-cool-script

# Test caching
New-ColorScriptCache -Name my-cool-script
Show-ColorScript -Name my-cool-script

Modifying Module Code

Fork the repository

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Follow existing code style
- Add comment-based help to functions
- Update version numbers appropriately
- Test thoroughly
Update documentation
- Update RELEASENOTES.md
- Update README.md if needed
- Add/update help files
- Include examples

Run tests

# Module smoke tests (includes ScriptAnalyzer)
pwsh -NoProfile -Command "& .\scripts\Test-Module.ps1"

# Full unit tests
Invoke-Pester -Path ./Tests

# Lint (treat warnings as failures)
pwsh -NoProfile -Command "& .\scripts\Lint-Module.ps1" -IncludeTests -TreatWarningsAsErrors

# (Optional) Auto-fix ScriptAnalyzer violations when available
pwsh -NoProfile -Command "& .\scripts\Lint-Module.ps1" -Fix

Commit your changes

git add .
git commit -m "feat: add awesome new feature"

Push and create PR
```
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub

Development Guidelines

PowerShell Style Guide

Use approved verbs: Get-, Set-, New-, Remove-, Build-, Clear-, Show-
PascalCase for function names
camelCase for variables
Full parameter names in scripts
Comment-based help for all public functions
Support -WhatIf and -Confirm for destructive operations

Comment-Based Help Format

function Verb-Noun {
    <#
    .SYNOPSIS
        Brief description

    .DESCRIPTION
        Detailed description

    .PARAMETER ParameterName
        Parameter description

    .EXAMPLE
        Verb-Noun -ParameterName Value
        Description of what this does

    .NOTES
        Additional information

    .LINK
        Related commands or URLs
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$ParameterName
    )

    # Implementation
}

ANSI Color Guidelines

Use ANSI escape sequences for maximum compatibility:

$esc = [char]27

# 16 colors
Write-Host "${esc}[31mRed Text${esc}[0m"

# 256 colors
Write-Host "${esc}[38;5;208mOrange${esc}[0m"

# RGB (24-bit)
Write-Host "${esc}[38;2;255;100;50mCustom Color${esc}[0m"

# Always reset
Write-Host "${esc}[0m"

Performance Considerations

Use [Console]::Write() for direct output when possible
Minimize object creation in loops
Cache frequently used values
Use StringBuilder for large string concatenations
Profile performance-critical sections

Testing Checklist

Before submitting:

Project Structure

ps-color-scripts-enhanced/
├── ColorScripts-Enhanced/
│   ├── ColorScripts-Enhanced.psd1    # Module manifest
│   ├── ColorScripts-Enhanced.psm1    # Module code
│   ├── en-US/                         # Help files
│   │   ├── about_ColorScripts-Enhanced.help.txt
│   │   ├── Show-ColorScript.md
│   │   ├── Get-ColorScriptList.md
│   │   ├── New-ColorScriptCache.md
│   │   └── Clear-ColorScriptCache.md
│   └── Scripts/                       # Colorscript files
│       ├── hearts.ps1
│       ├── mandelbrot-zoom.ps1
│       └── ...                        # Render logic only; caching handled by module
├── scripts/                           # Build and utility scripts
│   ├── build.ps1                      # Build script
│   ├── Test-Module.ps1                # Test harness
│   ├── Lint-Module.ps1                # Linting script
│   └── ...                            # Other utility scripts
├── docs/                              # Documentation
│   ├── examples/                      # Example code and conversions
│   └── oversized-colorscripts/        # Large colorscripts
├── assets/                            # Static assets
│   └── ansi-files/                    # Source ANSI art files
├── README.md                          # Main documentation
├── RELEASENOTES.md                    # Version history
├── CONTRIBUTING.md                    # This file
├── LICENSE                            # Unlicense License
└── .gitignore                         # Git ignore rules

Pull Request Process

Before Starting
- Fork the repository
- Create a feature branch: git checkout -b feature/your-feature
- Update .gitignore if needed
During Development
- Follow code style guidelines
- Add tests for new functionality
- Update relevant documentation
- Run full test suite: npm run verify
- Run linting: npm run lint:fix
Before Submitting PR
- All tests pass: npm run verify
- Linting clean: npm run lint
- Documentation updated
- Examples work correctly
- Commit messages follow Conventional Commits
- Tested on multiple PowerShell versions
Creating the PR
- Use descriptive title
- Link related issues: Closes #123
- Include description of changes
- Mention breaking changes (if any)
- Request review from maintainers
After PR Submission
- Address review feedback
- Keep branch up to date with main
- Rebase if necessary
- Wait for maintainer approval

Commit Message Convention

We follow Conventional Commits:

type(scope): subject

body

footer

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code formatting
refactor: Code restructuring
perf: Performance improvement
test: Test changes
chore: Build or dependency changes

Examples

feat(cache): add parallel cache building

Implemented multi-threaded cache generation
for improved performance on large collections.

Closes #456

fix(caching): resolve cache invalidation bug

Cache was not invalidating when scripts
were updated in certain scenarios.

Contribution Types

Adding Colorscripts

Difficulty: Easy 🟢

Steps:

Create script file in ColorScripts-Enhanced/Scripts/
Use lowercase-with-hyphens naming
Add to ScriptMetadata.psd1
Test with: Show-ColorScript -Name your-script
Submit PR with description

Requirements:

Example:

# File: ColorScripts-Enhanced/Scripts/my-awesome-art.ps1
$esc = [char]27
$red = "$esc[38;2;255;0;0m"
$reset = "$esc[0m"

Write-Host "${red}Beautiful ANSI Art${reset}"

Bug Reports

Difficulty: Easy 🟢

When reporting:

Use bug report template
Include:
- PowerShell version ($PSVersionTable)
- Operating system and terminal
- Exact reproduction steps
- Error messages and logs
- Attached screenshots (if visual)

Feature Requests

Difficulty: Easy 🟢

When requesting:

Use feature request template
Include:
- Clear description of desired functionality
- Use cases and benefits
- Proposed implementation approach
- Examples or mockups (if applicable)

Documentation

Difficulty: Easy 🟢

Areas for improvement:

Code Contributions

Difficulty: Medium 🟡 to Hard 🔴

Examples:

New cmdlet (Hard 🔴)
Bug fix (Medium 🟡)
Performance optimization (Medium 🟡 to Hard 🔴)
Refactoring (Medium 🟡)
Test additions (Easy 🟢 to Medium 🟡)

For complex changes:

Open issue first to discuss approach
Wait for maintainer feedback
Implement with tests
Submit PR with detailed explanation

Development Workflow Details

Local Setup

# 1. Clone repository
git clone https://github.com/yourusername/ps-color-scripts-enhanced.git
cd ps-color-scripts-enhanced

# 2. Install dependencies
npm install

# 3. Verify setup
npm run build
npm test

Making Changes

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes to files

# 3. Test changes
npm test
npm run lint

# 4. Run full validation
npm run verify

# 5. Commit changes
git add .
git commit -m "feat(module): add new feature"

# 6. Push to fork
git push origin feature/my-feature

Handling Conflicts

If your PR has conflicts:

# Update from main
git fetch upstream
git rebase upstream/main

# Resolve conflicts in your editor, then:
git add .
git rebase --continue
git push origin feature/my-feature -f

Testing Your Contributions

Unit Tests

# Run all tests
npm run test:pester

# Run specific test file
Invoke-Pester -Path ./Tests/MyTest.Tests.ps1

# Run with coverage report
Invoke-Pester -Path ./Tests -CodeCoverage ColorScripts-Enhanced/ColorScripts-Enhanced.psm1

Integration Tests

# Test full workflow
New-ColorScriptCache -Force
Show-ColorScript
Get-ColorScriptList
Export-ColorScriptMetadata -IncludeFileInfo

Smoke Tests

# Quick validation
npm test

Linting

# Standard linting
npm run lint

# With auto-fix
npm run lint:fix

# Strict mode (treat warnings as errors)
npm run lint:strict

Testing Matrix

Test your changes across:

Platform	PowerShell 5.1	PowerShell 7.x	Status
Windows	✅	✅	Required
macOS	❌	✅	Recommended
Linux	❌	✅	Recommended

Use GitHub Actions or test locally:

# PowerShell 5.1 (Windows only)
powershell -NoProfile -Command "& .\scripts\Test-Module.ps1"

# PowerShell 7
pwsh -NoProfile -Command "& .\scripts\Test-Module.ps1"

Performance Benchmarking

Before optimization PRs, include benchmarks:

# Measure before
$before = Measure-Command { Show-ColorScript -Name mandelbrot-zoom -NoCache }

# Make your changes...

# Measure after
$after = Measure-Command { Show-ColorScript -Name mandelbrot-zoom -NoCache }

Write-Host "Before: $($before.TotalMilliseconds)ms"
Write-Host "After: $($after.TotalMilliseconds)ms"
Write-Host "Improvement: $(([math]::Round($before.TotalMilliseconds / $after.TotalMilliseconds, 2)))x"

Documentation Standards

Code Comments

# Good: Explains WHY not WHAT
# We use StringBuilder for performance with large outputs
$sb = [System.Text.StringBuilder]::new()

# Bad: Restates obvious code
# Increment counter
$i++

Help Documentation

All public functions must have comment-based help:

<#
.SYNOPSIS
    One-line summary (critical)

.DESCRIPTION
    Detailed explanation of what it does.
    Include use cases and behavior.

.PARAMETER Name
    Description of parameter.
    Include type and valid values.

.PARAMETER Force
    Switch to override default behavior.

.EXAMPLE
    Show-ColorScript -Name "hearts"

    Displays the "hearts" colorscript.

.EXAMPLE
    Show-ColorScript -Random

    Displays a random colorscript.

.INPUTS
    System.String. You can pipe a script name.

.OUTPUTS
    None or System.String (with -PassThru)

.NOTES
    Additional technical notes.

.LINK
    Get-ColorScriptList
    New-ColorScriptCache
    https://github.com/Nick2bad4u/ps-color-scripts-enhanced
#>

Approval Process

Automatic Checks

✅ Tests pass
✅ Linting passes
✅ No security issues
✅ Coverage maintained

Manual Review

Code quality
Design appropriateness
Documentation completeness
Breaking changes assessment

Approval Criteria

PR can be merged when:

All automatic checks pass
At least one maintainer approves
No requested changes remain
Commits are clean

Recognition

Contributors will be recognized:

In CHANGELOG.md for each release
In CONTRIBUTORS.md
GitHub "Contributors" page
Release announcements (optional)

Resources for Contributors

Documentation (2)

Tools

Community

GitHub Discussions
GitHub Issues
PowerShell Discord (if available)

Getting Help

Questions: Open a GitHub Discussion
Bug Reports: Use issue template
Feature Ideas: Use issue template or Discussion
Code Review: Ask in PR comments
General Help: Check existing docs first

Version Numbering

Format: YYYY.MM.DD.BuildNumber

Example: 2025.10.09.1625

YYYY: Year
MM: Month (01-12)
DD: Day (01-31)
BuildNumber: Sequential number for multiple releases per day

Questions

📖 Check README.md
📚 Review docs/ folder
💬 Open a Discussion
🐛 Check existing Issues
👥 Ask in PR comments

License

By contributing, you agree your contributions will be licensed under the Unlicense License.

Thank You

Your contributions make ColorScripts-Enhanced better for the entire PowerShell community! 🎨✨

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to ColorScripts-Enhanced

Code of Conduct

How to Contribute

Reporting Bugs

Suggesting Features

Contributing Code

Adding New Colorscripts

Modifying Module Code

Development Guidelines

PowerShell Style Guide

Comment-Based Help Format

ANSI Color Guidelines

Performance Considerations

Testing Checklist

Project Structure

Pull Request Process

Commit Message Convention

Types

Examples

Contribution Types

Adding Colorscripts

Bug Reports

Feature Requests

Documentation

Code Contributions

Development Workflow Details

Local Setup

Making Changes

Handling Conflicts

Testing Your Contributions

Unit Tests

Integration Tests

Smoke Tests

Linting

Testing Matrix

Performance Benchmarking

Documentation Standards

Code Comments

Help Documentation

Approval Process

Automatic Checks

Manual Review

Approval Criteria

Recognition

Resources for Contributors

Documentation (2)

Tools

Community

Getting Help

Version Numbering

Questions

License

Thank You