Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
DJ-Assistant is a local-first preparation tool for professional DJs. The project currently operates in Phase 1 (Analysis Engine). All contributions must align with the Canonical Documentation and the System Design Plan (SDD). The project uses audit findings tracked as TA.1–TA.14 to guide execution.
Sources: CONTRIBUTING.md:3-5, README.md:14, CHANGELOG.md:8
Development Prerequisites
You must install the following software versions to build and test the project:
- Node.js: Version 20 or higher.
- pnpm: Version 10.14.0 or higher.
- Rust: Version 1.82 or higher.
Sources: README.md:273, package.json:6
Workspace Structure
The project uses a monorepo structure for both Node.js and Rust components.
| Component | Technology | Description |
|---|---|---|
@dj-assistant/desktop | Tauri, React, Tailwind | Main desktop application frontend. |
@dj-assistant/api | Fastify, TypeScript | Optional cloud API skeleton. |
@dj-assistant/shared | TypeScript | Shared types and utilities across packages. |
dj-assistant-core | Rust | Core logic: scanning, hashing, and SQLite management. |
dj-assistant-analysis | Rust | Audio engine: ONNX inference and decoding. |
Sources: README.md:292-298, package.json:9-15, apps/desktop/src-tauri/Cargo.toml:19-22
Contribution Process
Follow this workflow to propose and implement changes to the codebase.
1. Planning and Reporting
Before writing code, check existing issues or open a new one. Provide clear titles and describe expected versus actual behavior. For analysis or cue issues, include sample metadata or anonymized fixture descriptions. Open a discussion for significant architectural changes. Do not submit large Pull Requests (PRs) that contradict the Canonical Spec.
Sources: CONTRIBUTING.md:17-25
2. Implementation Workflow
The following diagram illustrates the standard sequence for implementing a change:
This flow ensures all changes meet the project's quality gates before merging.
Sources: CONTRIBUTING.md:27-33
3. Commit Standards
The project enforces Conventional Commits. Use the following formats for commit messages:
feat(analysis):for new analysis features.fix(desktop):for desktop bug fixes.docs:for documentation updates.test:for adding or updating tests.
Sources: CONTRIBUTING.md:36-42
Validation and Testing
You must validate all changes locally using the CI pipeline before pushing to the repository.
Local CI Pipeline
The pnpm ci:local command mirrors the GitHub Actions pipeline. It executes the following steps in order:
The pipeline ensures code style consistency and functional correctness.
Sources: package.json:22-23, README.md:280-285
Build and Test Commands
| Task | Command |
|---|---|
| Run Desktop Dev | pnpm dev:desktop |
| Full Local CI | pnpm ci:local |
| Portable Local CI | pnpm ci:local:portable |
| Rust Unit Tests | pnpm rust:test |
| Linting | pnpm lint |
| Formatting | pnpm format |
Sources: package.json:9-24
Task Tracking and Documentation
The project automates documentation updates for completed tasks. The scripts/update-task-docs.py script checks off Phase 0 and Phase 1 tasks in docs/sdd/04-TASKS.md and docs/engineering/DEVELOPMENT_TASK_LIST.md. It uses explicit task IDs like T0.1.1 to ensure accuracy.
Sources: scripts/update-task-docs.py:16-56
Project Principles
All contributions must uphold four non-negotiable principles:
- Local-first: Core analysis and storage happen on-device.
- Non-destructive: Source audio files remain untouched.
- User Control: Automation is previewable and reversible.
- Transparency: Sequencing logic is deterministic and auditable.
Sources: README.md:121
Code of Conduct
Maintain a respectful and constructive environment. Focus on the best outcomes for professional DJs. Harassment or bad-faith contributions result in immediate exclusion from the project.
Sources: CONTRIBUTING.md:46-48