Deadlock Mod Manager
Developer Documentation

Contributing Guidelines

How to contribute code, documentation and translations to Deadlock Mod Manager

AI-Assisted Contributions

We use AI tools in our development workflow and encourage contributors to use them responsibly as well. See our AI Policy for guidelines.

AI agents working on this codebase should also read AGENTS.md for project-specific instructions.

Getting Started

Before You Begin

  1. Read the Code of Conduct: Familiarize yourself with our community guidelines
  2. Set up your development environment: Follow the Development Setup guide
  3. Understand the project structure: Review the Project Structure documentation
  4. Join the community: Connect with us on Discord for discussions and support

Types of Contributions

We accept various types of contributions:

  • 🐛 Bug fixes - Fix issues and improve stability
  • ✨ New features - Implement new functionality
  • 📚 Documentation - Improve guides, API docs, and examples
  • 🌐 Translations - Add or improve language support
  • 🔧 Code quality - Refactoring, performance improvements, and cleanup
  • 🧪 Testing - Add or improve test coverage
  • 🎨 Design - UI/UX improvements and design assets

Development Workflow

1. Planning Your Contribution

For Bug Fixes

  1. Check existing issues: Search for existing bug reports
  2. Create an issue: If none exists, create a detailed bug report
  3. Discuss the approach: Comment on the issue with your proposed solution
  4. Get approval: Wait for maintainer feedback before starting work

For New Features

  1. Create a feature request: Open an issue with the feature template
  2. Discuss the design: Engage with maintainers and community for feedback
  3. Create a design document: For complex features, outline the approach
  4. Get approval: Ensure the feature aligns with project goals
  5. Break down the work: Split large features into smaller, manageable tasks

2. Setting Up Your Fork

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/deadlock-mod-manager.git
cd deadlock-mod-manager

# Add the upstream repository
git remote add upstream https://github.com/deadlock-mod-manager/deadlock-mod-manager.git

# Install dependencies
pnpm install

# Set up the development environment
cp env.example .env
docker compose up -d
pnpm db:push

3. Creating a Feature Branch

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create a new feature branch
git checkout -b feature/your-feature-name
# or for bug fixes
git checkout -b fix/issue-description

4. Making Changes

Code Quality Guidelines

Follow these essential guidelines when making changes:

TypeScript Standards:

  • Never use any types - use proper type definitions
  • Use interfaces for object shapes that will be extended
  • Use type aliases for complex types and unions
  • Implement proper error handling with typed exceptions

React Component Guidelines:

  • Use functional components with hooks
  • Keep components small and focused on single responsibilities
  • Use proper prop typing with TypeScript interfaces
  • Implement proper error boundaries where needed

Styling Guidelines:

  • Use Tailwind CSS v4 with configuration in index.css rather than tailwind.config.js
  • Follow the existing design system and component patterns
  • Ensure responsive design for all screen sizes
  • Use semantic HTML elements for accessibility

Backend Guidelines:

  • Use structured logging with the @deadlock-mods/logging package
  • Implement proper request validation with Zod schemas
  • Follow REST API conventions for new endpoints
  • Use database transactions for multi-step operations

File Organization

When adding new files:

# For React components
src/components/[ComponentName]/
├── index.tsx           # Main component
├── [ComponentName].tsx # Implementation (if complex)
├── types.ts           # Component-specific types
└── hooks.ts           # Component-specific hooks

# For API endpoints
src/routers/[feature]/
├── index.ts           # Router exports
├── handlers.ts        # Request handlers
├── validation.ts      # Request/response schemas
└── types.ts          # Feature-specific types

# For shared utilities
packages/shared/src/
├── utils/            # Utility functions
├── types/           # Shared type definitions
├── constants/       # Application constants
└── validators/      # Shared validation schemas

5. Testing Your Changes

Running Tests

# Run all tests
pnpm test

# Run tests for specific packages
pnpm --filter desktop test
pnpm --filter api test

Writing Tests

Unit Tests for Components:

import { render, screen } from "@testing-library/react";
import { ModCard } from "./ModCard";

describe("ModCard", () => {
  it("displays mod information correctly", () => {
    const mockMod = {
      id: 1,
      name: "Test Mod",
      description: "A test mod",
      author: "Test Author",
    };

    render(<ModCard mod={mockMod} />);

    expect(screen.getByText("Test Mod")).toBeInTheDocument();
    expect(screen.getByText("Test Author")).toBeInTheDocument();
  });
});

Integration Tests for API:

import { test, expect } from "bun:test";
import { app } from "../src/index";

test("GET /api/mods returns mod list", async () => {
  const response = await app.request("/api/mods");
  const data = await response.json();

  expect(response.status).toBe(200);
  expect(Array.isArray(data.mods)).toBe(true);
});

6. Code Quality Checks

Before committing, ensure your code passes all quality checks:

# Run linting
pnpm lint

# Fix linting issues automatically
pnpm lint:fix

# Format code
pnpm format:fix

# Type checking
pnpm check-types

Git Hooks

Lefthook runs a pre-commit hook configured in lefthook.yml. It formats staged files with oxfmt, fixes staged JavaScript and TypeScript with oxlint, runs knip when JavaScript, TypeScript or package files change, checks staged changesets, and runs cargo clippy in each Rust workspace whose files changed. It does not run the type checker, so run pnpm check-types yourself.

Commit Guidelines

Commit Message Format

Use Conventional Commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring without functionality changes
  • test: Adding or updating tests
  • chore: Maintenance tasks, dependency updates
  • ci: CI/CD configuration changes

Examples:

feat(desktop): add mod search functionality
fix(api): handle pagination edge cases properly
docs(readme): update installation instructions
refactor(shared): extract common validation logic
test(desktop): add unit tests for mod installation
chore(deps): update Tauri to v2.1.0

Scope Guidelines

Use these scopes to indicate the affected area:

  • desktop: Desktop application changes
  • api: API server changes
  • web: Web application changes
  • docs: Documentation changes
  • shared: Shared packages changes
  • database: Database schema or migration changes
  • ci: CI/CD pipeline changes

Pull Request Process

1. Preparing Your PR

Before submitting:

# Sync with upstream
git fetch upstream main
git rebase upstream/main

# Run final checks
pnpm check-types
pnpm build

# Push to your fork
git push origin feature/your-feature-name

2. Creating the Pull Request

Use the pull request template and provide:

PR Title: Use conventional commit format

feat(desktop): add advanced mod filtering options

PR Description:

## Description

Brief description of the changes and motivation.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] I have tested these changes locally
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Screenshots (if applicable)

Include screenshots of UI changes.

## Checklist

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have read and followed the contributing guidelines

3. Code Review Process

What to Expect

  1. Automated Checks: CI/CD pipeline runs tests and quality checks
  2. Maintainer Review: Project maintainers review the code
  3. Feedback Incorporation: Address review comments
  4. Approval: Maintainer approval required for merge
  5. Merge: Maintainers handle the merge process

Review Criteria

Reviewers look for:

  • Code Quality: Follows project standards and best practices
  • Functionality: Changes work as intended and don't break existing features
  • Testing: Adequate test coverage for changes
  • Documentation: Necessary documentation updates included
  • Performance: No negative performance impact
  • Security: No security vulnerabilities introduced

4. Addressing Review Feedback

# Make requested changes
git add .
git commit -m "fix: address review feedback"

# If you need to modify commit history
git rebase -i HEAD~n  # where n is number of commits to modify

# Push changes
git push origin feature/your-feature-name

Specific Contribution Areas

Frontend Development (Desktop App)

Components and async operations

Reuse the existing hooks instead of writing new install or download logic. For example, useInstall in apps/desktop/src/hooks/use-install.ts installs a mod into the active profile. Run new async operations through React Query mutations and read their pending and error state from the mutation instead of keeping loading flags in useState. Report errors with the initialized logger (@/lib/logger) and the existing mutation error UI, not console.

Add user-facing text to apps/desktop/src/locales/en.json and read it with useTranslation from react-i18next. Other locales are synced from Crowdin.

State Management

Persisted application state lives in the Zustand store in apps/desktop/src/lib/store/, composed from domain slices. Read it with usePersistedStore and a selector. Changing the persisted shape needs a migration in migrate.ts. Remote data from the API belongs in React Query.

See .agents/context/CODING.md for the full conventions.

Backend Development (API)

API Endpoints

API routes are oRPC procedures in apps/api/src/routers/. Each procedure declares its HTTP route and Zod input and output schemas, and the OpenAPI document is generated from them. Shared request and response schemas live in packages/shared/src/schemas/. This is the v2 single-mod route from apps/api/src/routers/v2/mods.ts:

getModV2: publicProcedure
  .route({ method: "GET", path: "/v2/mods/{id}" })
  .input(ModIdParamSchema)
  .output(ModSchema)
  .handler(async ({ input }) => {
    const mod = await modRepository.findByRemoteId(input.id);
    if (!mod) {
      throw new ORPCError("NOT_FOUND");
    }
    return toModDto(mod);
  }),

Use protectedProcedure for routes that need a signed-in user, and createRateLimitMiddleware from apps/api/src/lib/orpc.ts for routes that need a rate limit.

Database Changes

Adding Migrations

Change the Drizzle schema in packages/database/src/schema/, then generate a migration:

pnpm --filter database db:generate

drizzle-kit compares the schema with the existing snapshots and writes the SQL migration to packages/database/drizzle/. Review the generated SQL before committing it.

Translation Contributions

All translations are managed on Crowdin. The English sources are the only locale files edited directly in the repo: apps/desktop/src/locales/en.json for the desktop app and apps/www/src/locales/en/*.json for the website (deadlockmods.app). Every other locale is synced back from Crowdin automatically via the Crowdin GitHub action.

Where to translate

Contribute translations at translate.deadlockmods.app. Do not edit non-English JSON files in the repo directly - they will be overwritten on the next Crowdin sync.

Contributing a Translation

  1. Go to translate.deadlockmods.app and sign in
  2. Pick a language and translate strings in the Crowdin editor
  3. Approved translations are proposed as a PR on this repo automatically

Requesting a New Language

Request a new language on Crowdin, or file an issue and coordinate in the #translations Discord channel.

Adding or Changing Source Strings

When adding new UI strings in a PR, add them to apps/desktop/src/locales/en.json (desktop app) or the matching namespace file in apps/www/src/locales/en/ (website; see apps/www/src/locales/README.md). Once your PR is merged to main, the Crowdin action uploads the new source strings for translators.

Translation Guidelines

  • Context Understanding: Understand the UI context before translating
  • Consistency: Use consistent terminology throughout
  • Length Considerations: Keep translations roughly the same length as originals
  • Placeholders: Don't translate placeholders like {{username}}
  • Cultural Adaptation: Adapt content to local culture when appropriate

Documentation Contributions

Improving Existing Documentation

  1. Identify gaps: Look for missing or unclear information
  2. Make improvements: Update or add content as needed
  3. Test examples: Ensure all code examples work correctly
  4. Update navigation: Modify meta.json files if adding new pages

Adding New Documentation

---
title: Your Page Title
description: Brief description of the page content
---

import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

# Your Page Title

Content goes here...

<Callout type="info" title="Important Note">
Highlight important information with callouts.
</Callout>

## Next Steps

<Cards>
  <Card 
    title="Related Guide" 
    description="Link to related documentation"
    href="/path-to-guide" 
  />
</Cards>

Community Guidelines

Communication

  • Be respectful: Treat all community members with respect
  • Be constructive: Provide helpful feedback and suggestions
  • Be patient: Remember that contributors have different experience levels
  • Be inclusive: Welcome newcomers and diverse perspectives

Getting Help

  1. Read the documentation: Check existing guides and documentation first
  2. Search issues: Look for existing discussions about your question
  3. Ask in Discord: Join our Discord community for real-time help
  4. Create an issue: For bugs or feature requests, create a GitHub issue

Recognition

Contributors are recognized through:

  • GitHub Contributors: Listed in repository contributors
  • Release Notes: Significant contributions mentioned in releases
  • Discord Roles: Special contributor roles in the Discord community
  • Contributor Spotlight: Featured contributors in community updates

Maintainer Guidelines

For Project Maintainers

Review Process

  1. Automated Checks: Ensure all CI checks pass
  2. Code Review: Review for quality, security, and consistency
  3. Testing: Verify functionality works as expected
  4. Documentation: Ensure documentation is updated if needed
  5. Breaking Changes: Assess impact of any breaking changes

Merge Guidelines

  • Squash and merge: For feature branches with multiple commits
  • Rebase and merge: For clean, single-commit changes
  • Merge commit: For complex features that benefit from commit history

Release Management

  • Semantic Versioning: Follow semver for all releases
  • Changelog: Maintain detailed changelog with all changes
  • Release Notes: Create detailed release notes for major releases
  • Backward Compatibility: Ensure API compatibility when possible

Getting Support

Need help with your contribution?

Thank You!

Your contributions make Deadlock Mod Manager better for everyone. Whether you're fixing a typo in the documentation or implementing a major feature, every contribution is valuable and appreciated. Welcome to the team! 🎉

On this page