CONTRIBUTING.md

Contributing to ColorAssembly

Thank you for your interest in contributing to ColorAssembly! This document provides guidelines and instructions for contributing.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Testing
• Submitting Changes
• Style Guide

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

• Go 1.21 or later
• Node.js 18 or later
• npm 9 or later

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/ColorAssembly.git
   cd ColorAssembly

3. Add the upstream remote:

   git remote add upstream https://github.com/CymbolTech/ColorAssembly.git

Development Setup

1. Install Go dependencies:

   go mod download

2. Install Node.js dependencies:

   npm install

3. Build the project:

   make build

4. Verify everything works:

   make ci

Making Changes

Branch Naming

Create a branch with a descriptive name:

• feature/add-color-mixing - New features
• fix/hex-parsing-issue - Bug fixes
• docs/improve-readme - Documentation
• refactor/optimize-conversion - Code refactoring

Commit Messages

Follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting, no code change
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance

Examples:

feat(converters): add CIELUV color space support
fix(hex): handle 3-character hex codes correctly
docs(readme): add usage examples

Testing

Running Tests

# Compile tests (no runtime execution)
make test-compile

# Run full test suite (requires Node.js WASM environment)
make test

# Run with coverage
make test-coverage

Writing Tests

• Place tests in the tests/ directory
• Use descriptive test names
• Include edge cases
• Test both valid and invalid inputs

Example test:

func TestRGBToHex(t *testing.T) {
    tests := []struct {
        name string
        rgb  models.RGB
        want string
    }{
        {"black", models.RGB{R: 0, G: 0, B: 0}, "000000"},
        {"white", models.RGB{R: 255, G: 255, B: 255}, "FFFFFF"},
        {"red", models.RGB{R: 255, G: 0, B: 0}, "FF0000"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := converters.RGBToHex(tt.rgb)
            if got.Hex != tt.want {
                t.Errorf("RGBToHex() = %v, want %v", got.Hex, tt.want)
            }
        })
    }
}

Submitting Changes

Pull Request Process

1. Update your branch with the latest upstream:

   git fetch upstream
   git rebase upstream/main

2. Ensure all tests pass:

   make ci

3. Push to your fork:

   git push origin your-branch-name

4. Create a Pull Request on GitHub

Pull Request Guidelines

• Fill out the PR template completely
• Link related issues using keywords (e.g., "Fixes #123")
• Keep PRs focused on a single concern
• Include tests for new functionality
• Update documentation as needed
• Ensure CI passes

Review Process

1. A maintainer will review your PR
2. Address any requested changes
3. Once approved, a maintainer will merge

Style Guide

Go Code

• Follow Effective Go
• Use gofmt for formatting
• Run go vet before committing
• Keep functions small and focused
• Document exported functions

TypeScript Code

• Use TypeScript strict mode
• Prefer const over let
• Use explicit types for function parameters
• Document public APIs with JSDoc

File Structure

ColorAssembly/
├── pkg/
│   ├── models/      # Color type definitions
│   ├── converters/  # Color space conversions
│   ├── generators/  # Color generation tools
│   ├── analyzers/   # Accessibility analysis
│   ├── helpers/     # Utility functions
│   ├── api/         # JavaScript API layer
│   └── binding/     # WASM bindings
├── src/             # TypeScript source
├── tests/           # Test files
├── tools/           # Build tools
└── dist/            # Build output

Questions?

Feel free to open an issue for questions or discussions. We're happy to help!