Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (92 loc) · 3.24 KB

CONTRIBUTING.md

File metadata and controls

129 lines (92 loc) · 3.24 KB

Contributing to Helix Trainer

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

Development Workflow

We follow a strict PR-based workflow. All changes go through:

  1. Feature branch from main
  2. Full check pipeline (format, tests, clippy, build)
  3. Pull request with CI checks
  4. Code review
  5. Merge only when green

Quick Start

# Clone repository
git clone https://github.com/bug-ops/helix-trainer.git
cd helix-trainer

# Create feature branch
git checkout -b feature/amazing-feature

Pre-Commit Checks

Important

All PRs must pass these checks. CI enforces them automatically with zero tolerance for warnings.

Always run before pushing:

# 1. Format (requires nightly)
cargo +nightly fmt

# 2. Tests (fast parallel runner)
cargo nextest run

# 3. Lints (zero warnings policy)
cargo clippy --all-targets --all-features -- -D warnings

# 4. Build verification
cargo build --release

Tip

With sccache configured, rebuilds are 5x faster (~10s vs ~54s).

Commit Guidelines

We use Conventional Commits:

Prefix Purpose Example
feat: New feature feat: add streak multiplier
fix: Bug fix fix: correct XP calculation
docs: Documentation docs: update installation guide
refactor: Code refactoring refactor: simplify command handler
test: Add/update tests test: add fsrs scheduler tests
chore: Maintenance chore: update dependencies
ci: CI/CD changes ci: add ARM64 builds

Pull Request Process

  1. Ensure all checks pass locally
  2. Update documentation if needed
  3. Add tests for new functionality
  4. Write a clear PR description
  5. Link related issues
  6. Wait for CI to pass
  7. Request review

Code Style

  • Follow idiomatic Rust patterns
  • Use rustfmt with nightly (enforced by CI)
  • Keep functions focused and small
  • Prefer explicit error handling over .unwrap()
  • Add doc comments for public APIs

Caution

No unsafe code without explicit justification and approval.

Adding Scenarios

Scenarios are defined in scenarios/en/*.toml. Each scenario must have:

[[scenarios]]
id = "unique_id"
name = "Human readable name"
description = "Clear description of what to achieve"

[scenarios.setup]
file_content = "initial text"
cursor_position = [0, 0]

[scenarios.target]
file_content = "expected result"
cursor_position = [0, 0]

[scenarios.solution]
commands = ["command", "sequence"]

[scenarios.metadata]
category = "Movement"  # Movement, Editing, Clipboard, Selection, Search, Advanced
difficulty = "Beginner"  # Beginner, Intermediate, Advanced
tags = ["relevant", "tags"]
commands_taught = ["w", "e"]

Run cargo nextest run scenario to validate all scenarios.

Testing

  • Unit tests: cargo nextest run
  • Specific test: cargo nextest run test_name
  • With coverage: cargo llvm-cov

Getting Help

  • Open an issue for bugs or feature requests
  • Check existing issues before creating new ones
  • Use discussion threads for questions

License

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