Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
251 lines (177 loc) · 5.9 KB

CONTRIBUTING.md

File metadata and controls

251 lines (177 loc) · 5.9 KB

Contributing to DeepCrate

Thank you for your interest in contributing to DeepCrate! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

  • Node.js 24+
  • pnpm
  • Docker (for testing)
  • Git

Development Setup

  1. Clone the repository
git clone https://github.com/jordojordo/deepcrate.git
cd deepcrate
  1. Install all dependencies
pnpm install

This installs dependencies for all workspace packages (server, ui, docs) from the root.

  1. Create config for development
cp examples/config.yaml.example config.yaml
# Edit config.yaml with your test credentials

Running Locally

Both (recommended)

pnpm dev    # Starts server on :8080 and ui on :5173 concurrently

Server only

pnpm -C server dev    # Starts on http://localhost:8080 with hot reload

DeepCrate runs as a single Node.js process. Background jobs (lb-fetch, catalog-discovery, slskd-downloader) are scheduled via node-cron.

You can also trigger jobs via the API actions endpoints (useful for local testing):

curl -X POST http://localhost:8080/api/v1/actions/lb-fetch
curl -X POST http://localhost:8080/api/v1/actions/catalog

UI only

pnpm -C ui dev    # Starts on http://localhost:5173, proxies to server

Running Tests

Run tests from the project root:

pnpm -C server test
pnpm -C ui test

Linting / Formatting / Typechecks

Script names can vary—use the repo's package.json as the source of truth—but these are the typical targets:

pnpm -C server lint
pnpm -C server typecheck

pnpm -C ui lint
pnpm -C ui typecheck

API Documentation

When the server is running, an interactive API reference (powered by Scalar) is available at:

http://localhost:8080/api/v1/docs

The raw OpenAPI spec can be found at http://localhost:8080/api/v1/openapi.json.

Building and Running with Docker

docker build -t deepcrate:dev .
docker run -v ./config.yaml:/config/config.yaml -v ./data:/data -p 8080:8080 deepcrate:dev

Project Structure

The server is Node.js/TypeScript and the ui is Vue 3. Local development is typically two processes (server on :8080, ui on :5173).

deepcrate/
├── server/
│   ├── src/                  # Node.js/TypeScript server code (Express + jobs)
│   ├── tests/                # Server tests
│   └── package.json
│
├── ui/
│   ├── src/
│   │   ├── components/        # Vue components
│   │   ├── views/             # Page components
│   │   ├── stores/            # Pinia stores
│   │   └── api/               # API client
│   └── package.json
│
├── docs/                      # Documentation
├── examples/                  # Example configs
└── Dockerfile

Data Directory

All state is stored in /data (mounted as a volume in Docker), including the SQLite DB and logs.

Making Changes

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation changes
  • refactor/description - Code refactoring

Commit Messages

Follow Conventional Commits:

feat: add manual search endpoint
fix: handle empty wishlist gracefully
docs: update API documentation
refactor: extract queue service

Pull Request Process

  1. Fork and branch from master
  2. Make your changes with tests
  3. Update documentation if needed
  4. Run tests and linting
  5. Submit PR with clear description

PR Checklist

  • Server tests pass (pnpm -C server test)
  • UI tests pass (pnpm -C ui test)
  • Linting passes (pnpm -C server lint and pnpm -C ui lint)
  • Documentation updated if needed
  • Commit messages follow convention
  • PR description explains the change

Development Guidelines

TypeScript/Node.js (Server)

  • Prefer small, single-purpose modules
  • Use async/await for I/O
  • Validate and sanitize external inputs at the edges (routes/controllers)
  • Keep route handlers thin; move logic into services
  • Add tests for bug fixes and new behavior
// Example: keep handlers thin and logic in services
import type { Request, Response } from "express";
import { approveQueueItems } from "@server/services/queue.js";

export async function approve(req: Request, res: Response) {
  const ids = Array.isArray(req.body?.ids) ? req.body.ids : [];
  const result = await approveQueueItems(ids);
  res.json({ ok: true, ...result });
}

TypeScript/Vue (UI)

  • Use Composition API with <script setup>
  • Use TypeScript for type safety
  • Keep components small and focused
  • Use Pinia for state management
<script setup lang="ts">
import { computed } from "vue";
import { useQueueStore } from "@/stores/queue";

const store = useQueueStore();
const pending = computed(() => store.pendingItems);
</script>

API Design

  • Follow REST conventions
  • Use meaningful HTTP status codes
  • Return consistent error format
  • Keep endpoints stable and documented

Testing

  • Write unit tests for business logic
  • Write integration tests for API endpoints
  • Use fixtures for test data
  • Mock external services where appropriate

Areas for Contribution

Good First Issues

Look for issues labeled good first issue:

  • Documentation improvements
  • UI polish
  • Bug fixes
  • Test coverage

Feature Ideas

  • Additional discovery sources (Spotify, Bandcamp)
  • Notification integrations (Discord, Telegram)
  • Statistics and analytics dashboard

Questions?

License

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

Thank you for contributing to DeepCrate!