Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (85 loc) · 5.81 KB

CONTRIBUTING.md

File metadata and controls

123 lines (85 loc) · 5.81 KB
Raw

Contributing to Vite Task

Prerequisites

Initial Setup

just init

This installs all required Rust tools (cargo-insta, typos-cli, cargo-shear, taplo-cli) and bootstraps the Node.js tooling.

Development Workflow

Officially, Vite Task is distributed as part of Vite+ and invoked via vp run. The vt binary (vite_task_bin crate) is an internal development CLI for working on this repo in pure Rust without building the full Vite+ stack. Use cargo run --bin vt to build and run locally during development. Don't reference vt in user-facing documentation — it's not a public interface.

vp run (Vite+) vt run (this repo)
Purpose End-user CLI Internal dev/testing
Config vite.config.ts (run block) vite-task.json
Distribution Bundled in Vite+ cargo run --bin vt
Scope Full toolchain (dev, build, test, lint, ...) Task runner only 
just ready    # Full quality check: typos, fmt, check, test, lint, doc
just fmt      # Format code (cargo fmt + cargo shear + vp fmt)
just check    # Check compilation with all features
just test     # Run all tests
just lint     # Clippy linting
just doc      # Generate documentation

Testing

Running Tests

cargo test                                              # All tests
cargo test -p vite_task_bin --test e2e_snapshots        # E2E snapshot tests
cargo test -p vite_task_plan --test plan_snapshots      # Plan snapshot tests
cargo test --test e2e_snapshots -- stdin                # Filter by test name
UPDATE_SNAPSHOTS=1 cargo test                           # Update snapshots

Integration tests that need Node.js or the packages/tools binaries (e.g. oxlint) are marked #[ignore] — and [[e2e]] cases in e2e snapshots.toml can opt in with ignore = true. Default cargo test runs only the tests that need nothing beyond the Rust toolchain; to run the rest:

pnpm install                           # at the workspace root (installs packages/tools and Chromium too)
cargo test -- --include-ignored        # run everything
cargo test -- --ignored                # run only the previously-ignored tests

You don't need pnpm install in test fixture directories. Playwright's bundled Chromium is unavailable on musl, so the Vitest browser fixture is skipped there.

Test Fixtures

  • Plan snapshots — crates/vite_task_plan/tests/plan_snapshots/fixtures/ — quicker, sufficient for testing task graph, resolved configs, program paths, cwd, and env vars
  • E2E snapshots — crates/vite_task_bin/tests/e2e_snapshots/fixtures/ — needed for testing actual execution, caching behavior, and output styling

See individual crate READMEs for crate-specific testing details.

Playground

The playground/ directory is a small workspace for manually testing the task runner. It has three packages (app → lib → utils) with cached tasks (build, test, lint, typecheck) and an uncached dev script.

cargo run --bin vt -- run -r build          # run build across all packages
cargo run --bin vt -- run -r --parallel dev  # start all dev scripts in parallel

See playground/README.md for the full task list and dependency structure.

Cross-Platform Development

This project must work on macOS, Linux, and Windows. Skipping tests on any platform is not acceptable, except on musl targets when an essential dependency or required platform capability is unavailable. Document the unavailable requirement and keep the skip scoped to musl.

  • Use #[cfg(unix)] / #[cfg(windows)] for platform-specific code
  • Use cross-platform libraries where possible (e.g., terminal_size instead of raw ioctl/ConPTY)

Cross-Platform Linting

After changes to fspy* or platform-specific crates, run cross-platform clippy:

just lint           # Native (host platform)
just lint-linux     # Linux via cargo-zigbuild
just lint-windows   # Windows via cargo-xwin

Code Conventions

Required Patterns

These are enforced by .clippy.toml:

Instead of Use
HashMap / HashSet FxHashMap / FxHashSet from rustc-hash
std::path::Path / PathBuf vite_path::AbsolutePath / RelativePath
std::format! vite_str::format!
String (for small strings) vite_str::Str
std::env::current_dir vite_path::current_dir
.to_lowercase() / .to_uppercase() cow_utils methods

Path Type System

All paths use vite_path for type safety:

  • AbsolutePath / AbsolutePathBuf — for internal data flow
  • RelativePath / RelativePathBuf — for cache storage and display

Use vite_path methods (strip_prefix, join, etc.) instead of converting to std::path. Only convert to std paths when interfacing with std library functions. Add necessary methods to vite_path rather than falling back.

macOS Performance Tip

Add your terminal app to the approved "Developer Tools" in System Settings > Privacy & Security. Your Rust builds will be ~30% faster.