Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (131 loc) · 6 KB

CONTRIBUTING.md

File metadata and controls

188 lines (131 loc) · 6 KB

Contributing to Wavecraft

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

Development Setup

Prerequisites

  • Rust (stable, 2024 edition)
  • Node.js 20+
  • CMake (for AU wrapper on macOS)

Getting Started

  1. Clone the repository:

    git clone https://github.com/RonHouben/wavecraft.git
cd wavecraft

  2. Install dependencies:

    cd ui && npm install

  3. Build and test:

    cd engine
cargo xtask test        # Run all tests
cargo xtask lint        # Check code quality
cargo xtask bundle      # Build plugin bundles

For detailed setup instructions, see the SDK Getting Started Guide.

SDK Contributor Dev Mode (canonical template)

When working in the Wavecraft monorepo, development runs against sdk-template/.

./scripts/setup-dev-template.sh   # materialize .template files + install sdk-template/ui deps
cargo xtask dev                   # runs dev servers against sdk-template/engine + sdk-template/ui

Coding Standards

Wavecraft follows strict coding standards to maintain code quality and consistency. Please read docs/architecture/coding-standards.md before contributing.

Key points:

  • Rust: Class-based architecture (non-React code), real-time safety in audio thread
  • TypeScript: Functional components with hooks, strict mode enabled
  • Formatting: Run cargo xtask lint --fix before committing
  • Testing: Add tests for new functionality
  • Commit messages: Use conventional commits format (feat:, fix:, docs:, etc.)

Pull Request Process

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes:

    • Follow the coding standards
    • Add tests for new functionality
    • Update documentation as needed

  3. Run quality checks:

    cargo xtask lint --fix  # Fix linting issues
cargo xtask test        # Run all tests

  4. Commit your changes:

    git commit -m "feat: add your feature description"

    Use conventional commit prefixes:

    • feat: — New feature
    • fix: — Bug fix
    • docs: — Documentation changes
    • refactor: — Code refactoring
    • test: — Adding or updating tests
    • chore: — Maintenance tasks

  5. Push and create PR:

    git push origin feature/your-feature-name

    Then open a pull request on GitHub using the provided template.

Testing Requirements

All contributions must include appropriate tests:

  • UI changes: Add unit tests using Vitest + React Testing Library
  • Engine changes: Add Rust unit tests and integration tests
  • Run tests locally: cargo xtask test before submitting PR

See Testing & Quality Standards for testing guidelines.

Testing CLI-Generated Plugins

When making changes to the SDK that affect generated plugins (templates, CLI, or engine crates), you must validate that wavecraft create produces a working project.

Standard workflow using --output flag:

# Generate a test plugin into your local SDK checkout's build directory
cargo run --manifest-path cli/Cargo.toml -- create TestPlugin \
   --output target/tmp/test-plugin

# Build and test the generated plugin
cd target/tmp/test-plugin
cargo run --manifest-path /path/to/wavecraft/cli/Cargo.toml -- start --install

Why use --output?

  • Isolates test artifacts from your working directory
  • Generated project lives inside SDK repo's target/ (gitignored)
  • Easy cleanup: rm -rf target/tmp/test-plugin
  • Avoids confusion between SDK development and test plugins

Key test scenarios:

  1. wavecraft create completes without errors
  2. wavecraft start builds without compile errors
  3. cargo xtask bundle produces valid plugin bundles
  4. Plugin loads in a DAW without crashes

Documentation

Update documentation when:

  • Adding new features or APIs
  • Changing existing behavior
  • Adding configuration options
  • Fixing bugs that might affect users

Documentation lives in docs/:

  • docs/guides/ — User-facing guides
  • docs/architecture/ — Technical architecture documents
  • docs/feature-specs/ — Feature specifications (for development)

CI/CD Pipeline

All PRs run through our CI pipeline:

  1. Linting — ESLint + Prettier (UI), Clippy + fmt (Engine)
  2. Type checking — TypeScript strict mode
  3. Tests — UI unit tests, Engine tests
  4. Build — VST3 + CLAP bundles (main branch only)

PRs must pass all CI checks before merging. See docs/guides/ci-pipeline.md for details.

Squash Merge Policy

All PRs are squashed on merge to keep the main branch history clean. Your PR title becomes the commit message, so make it descriptive.

Documentation Structure

Architecture documentation lives in docs/architecture/ and follows these conventions:

  • Overview hubs (coding-standards.md, high-level-design.md) — Navigation entry points with links to topic-specific docs
  • Topic-specific docs — Self-contained documents for specific domains (e.g., coding-standards-rust.md, sdk-architecture.md)
  • Target size: 150–600 lines per document
  • Required sections: Title, description, Related Documents, content

See the navigation tables in Coding Standards and High-Level Design for the full document list.

Questions or Need Help?

License

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

Thank you for contributing to Wavecraft! 🎵