Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (66 loc) · 3.48 KB

CONTRIBUTING.md

File metadata and controls

78 lines (66 loc) · 3.48 KB

Contributing to DevKeys

Thanks for your interest in improving DevKeys! This guide explains how the project is organised, how to run it locally, and what we look for in pull requests.

Quick Start

  1. Fork + clone the repository.
  2. Install dependencies from the repo root: 
    pnpm install
  3. (Optional) Install the Rust WASM target if you plan to touch the engine: 
    rustup target add wasm32-unknown-unknown
  4. Launch the web app: 
    pnpm dev:web
    Visit the printed URL (default http://localhost:5173) and you should see Algorithms Mode with language/prompt menus, animated metrics, and the monochrome grid backdrop.

Before opening a PR

  • Run pnpm verify from the repo root. This lints, type-checks, builds the app, and executes the Rust tests.
  • If you updated the engine, rebuild the WASM bundle (optional but ideal) with pnpm build:wasm.
  • Include screenshots or GIFs for visible UI changes. The more context reviewers have, the quicker the merge.
  • Keep commits focused; smaller changesets are easier to review and revert if necessary.

Project Layout Recap

  • apps/web/ — React + Vite app using Tailwind, highlight.js, Zustand, and framer-motion.
  • crates/engine/ — Rust diff/scoring engine exposed through wasm-bindgen.
  • docs/ — Living documentation. Update relevant pages if your change affects behaviour, architecture, or roadmap items.
  • apps/web/src/content/ — Built-in prompt packs (localPacks.ts consolidates them for the runtime bundle).

Content Pack Schema

Add new packs inside apps/web/src/content/packs/ and register them in localPacks.ts.

{
  "packId": "algorithms.v2",
  "title": "Algorithms — Extended",
  "description": "Extra sorting and graph snippets.",
  "items": [
    {
      "id": "binary_search_iter_js",
      "language": "javascript",
      "snippet": "function binarySearch(...) { ... }"
    }
  ]
}

Fields such as difficulty or notes are optional today, but please include them if you plan to use them later—future filtering hinges on consistent metadata.

Coding Standards

  • TypeScript/React
    • Follow the existing Tailwind utility patterns; keep animation timing ≤150 ms unless there’s a clear reason.
    • Prefer small composable hooks/components (useLanguageSelection, MenuBar, etc.).
    • Run pnpm lint:web and pnpm typecheck:web if you’re working on the UI.
  • Rust
    • Keep logic deterministic—the Rust WASM module is the single source of truth for metrics.
    • Use cargo fmt and cargo clippy --all-targets --all-features before committing larger changes.
    • Add unit tests for new diff behaviour.

Testing

  • pnpm --filter @devkeys/web test → Vitest suite (use it for hooks, utils, and component behaviour).
  • cargo test -p devkeys_engine → Rust engine tests.
  • wasm-pack test --headless --firefox → Optional, once browser WASM tests are introduced.

Filing Issues

  • Include reproduction steps, expected vs actual behaviour, and environment details (OS, browser, Node version).
  • Tag UI issues with screenshots when possible.
  • Suggest a fix or link to the relevant code path if you already investigated.

Community Guidelines

  • Be respectful and constructive—follow the Contributor Covenant.
  • Privacy-first contributions only (no hidden telemetry or unexpected network calls).
  • Encourage pairing or async walkthroughs when implementing larger features.

Happy hacking—and thanks again for supporting DevKeys! ✨