Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
293 lines (206 loc) · 7.08 KB

CONTRIBUTING.md

File metadata and controls

293 lines (206 loc) · 7.08 KB

Contributing to Numix VS Code Theme

Thank you for your interest in contributing to the Numix VS Code Theme! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project follows the Numix Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

  • Node.js 22.x or later
  • npm 10.x or later
  • Git
  • VS Code 1.60 or later (for testing)

Repository Structure

numix-vscode-theme/
├── numix-theme.json      # Theme definition (colors, token colors)
├── package.json          # Extension manifest
├── LICENSE               # GPL-3.0 license
├── CHANGELOG.md          # Change history
├── CONTRIBUTING.md       # This file
├── README.md             # Project documentation
├── Makefile              # Build automation
├── dev.sh               # Development script
├── .nvmrc               # Node.js version
├── .gitignore           # Git ignore rules
├── .github/
│   └── workflows/
│       ├── ci.yml       # CI pipeline
│       └── release.yml  # Release pipeline
└── .vscode/
    ├── extensions.json  # Recommended extensions
    ├── settings.json   # Editor settings
    ├── launch.json     # Debug configurations
    └── tasks.json      # VS Code tasks

Development Setup

1. Fork the Repository

  1. Go to numix-vscode-theme
  2. Click the "Fork" button in the top-right corner
  3. Clone your fork:
git clone https://github.com/YOUR-USERNAME/numix-vscode-theme.git
cd numix-vscode-theme

2. Set Up Development Environment

# Using nvm (recommended)
nvm install 22
nvm use 22

# Install development dependencies
npm install -g @vscode/vsce

# Verify installation
vsce --version

3. Create a Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/your-bug-description

Making Changes

Theme Development

Adding/Modifying Colors

The theme is defined in numix-theme.json. The file contains:

  1. Colors section - UI element colors (editor background, syntax highlighting, etc.)
  2. Token colors - Syntax highlighting rules
  3. Semantic token colors - Modern semantic highlighting

Color Guidelines

  • Use WCAG AA compliant colors (minimum 4.5:1 contrast ratio)
  • For dark backgrounds, use lighter foreground colors
  • Follow the Numix color palette when possible
  • Test colors for color blindness compatibility

Example: Adding a New Color

{
  "name": "New Feature Color",
  "scope": ["entity.name.feature"],
  "settings": {
    "foreground": "#81c784",
    "fontStyle": "italic"
  }
}

Testing Your Changes

  1. Validate locally:
# Using npm
npm run validate

# Using Make
make validate

# Using dev.sh
./dev.sh validate
  1. Test in VS Code:
# Press F5 to open Extension Development Host
# Or manually:
code --install-extension numix-vscode-theme-0.1.0.vsix
  1. Run tests:
make test

Building the Extension

# Package the extension
npm run package

# Or use Make
make package

# Or use dev.sh
./dev.sh package

Submitting Changes

1. Commit Your Changes

Write clear, descriptive commit messages:

feat(theme): Add new syntax highlighting for Rust

- Added support for Rust lifetime annotations
- Updated semantic tokens for better type recognition
- Fixed contrast ratio for error messages (WCAG AA compliant)

Closes #123

2. Push to Your Fork

git push origin feature/your-feature-name

3. Create a Pull Request

  1. Go to the original repository
  2. Click "New Pull Request"
  3. Select your fork and branch
  4. Fill in the PR template
  5. Submit the PR

Pull Request Guidelines

  • One focus per PR: Keep changes small and focused
  • Include tests: Add or update tests for new features
  • Update documentation: Update README, CHANGELOG, or add inline comments
  • Pass CI: Ensure all checks pass before requesting review
  • Describe changes: Explain what you changed and why

Style Guidelines

Code Style

  • Use 2 spaces for indentation
  • Use semicolons in JavaScript
  • Follow JSON formatting standards

Color Style

  • Use lowercase hex colors: #2a2a2a not #2A2A2A
  • Group related colors together
  • Use comments to explain color choices
  • Maintain consistent saturation/brightness levels

Naming Conventions

  • Use descriptive names: editor.selectionBackground not selBg
  • Follow VS Code color naming patterns
  • Use consistent casing: camelCase for keys, Title Case for names

Token Scope Naming

Follow TextMate scope naming:

  • source.js - JavaScript source
  • entity.name.function - Function names
  • keyword.control - Control keywords
  • storage.type - Type declarations

Accessibility Requirements

All contributions must maintain accessibility standards:

Contrast Ratios

Text Type Minimum Ratio
Normal text 4.5:1 (AA)
Large text 3:1 (AA)
UI components 3:1 (AA)

Testing Accessibility

  1. Contrast checker: Use WebAIM Contrast Checker
  2. Color blindness: Test with Coblis
  3. Keyboard navigation: Ensure focus states are visible

Color Blindness Guidelines

  • Avoid red/green alone for status (use icons + color)
  • Ensure 25%+ luminance difference between similar colors
  • Use blue for critical information (universally visible)
  • Test with deuteranopia, protanopia, and tritanopia simulations

Communication

Issues

  • Use GitHub Issues for:
    • Bug reports
    • Feature requests
    • Accessibility concerns
    • Questions about the theme

Discussions

  • Use GitHub Discussions for:
    • Questions
    • Ideas and brainstorming
    • Show and tell (share your configs)

Security

For security vulnerabilities, please email maintainers directly instead of opening public issues.

Recognition

Contributors will be recognized in:

  • CHANGELOG.md
  • GitHub release notes
  • Project README (for significant contributions)

Thank You!

Your contributions help make the Numix VS Code Theme better for everyone. We appreciate your time and effort!

Questions? Open an issue or start a discussion.