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
- Read the Code of Conduct: Familiarize yourself with our community guidelines
- Set up your development environment: Follow the Development Setup guide
- Understand the project structure: Review the Project Structure documentation
- 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
- Check existing issues: Search for existing bug reports
- Create an issue: If none exists, create a detailed bug report
- Discuss the approach: Comment on the issue with your proposed solution
- Get approval: Wait for maintainer feedback before starting work
For New Features
- Create a feature request: Open an issue with the feature template
- Discuss the design: Engage with maintainers and community for feedback
- Create a design document: For complex features, outline the approach
- Get approval: Ensure the feature aligns with project goals
- 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:push3. 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-description4. Making Changes
Code Quality Guidelines
Follow these essential guidelines when making changes:
TypeScript Standards:
- Never use
anytypes - 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.cssrather thantailwind.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/loggingpackage - 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 schemas5. Testing Your Changes
Running Tests
# Run all tests
pnpm test
# Run tests for specific packages
pnpm --filter desktop test
pnpm --filter api testWriting 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-typesGit 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 featuresfix: Bug fixesdocs: Documentation changesstyle: Code style changes (formatting, etc.)refactor: Code refactoring without functionality changestest: Adding or updating testschore: Maintenance tasks, dependency updatesci: 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.0Scope Guidelines
Use these scopes to indicate the affected area:
desktop: Desktop application changesapi: API server changesweb: Web application changesdocs: Documentation changesshared: Shared packages changesdatabase: Database schema or migration changesci: 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-name2. Creating the Pull Request
Use the pull request template and provide:
PR Title: Use conventional commit format
feat(desktop): add advanced mod filtering optionsPR 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 guidelines3. Code Review Process
What to Expect
- Automated Checks: CI/CD pipeline runs tests and quality checks
- Maintainer Review: Project maintainers review the code
- Feedback Incorporation: Address review comments
- Approval: Maintainer approval required for merge
- 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-nameSpecific 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:generatedrizzle-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
- Go to translate.deadlockmods.app and sign in
- Pick a language and translate strings in the Crowdin editor
- 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
- Identify gaps: Look for missing or unclear information
- Make improvements: Update or add content as needed
- Test examples: Ensure all code examples work correctly
- 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
- Read the documentation: Check existing guides and documentation first
- Search issues: Look for existing discussions about your question
- Ask in Discord: Join our Discord community for real-time help
- 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
- Automated Checks: Ensure all CI checks pass
- Code Review: Review for quality, security, and consistency
- Testing: Verify functionality works as expected
- Documentation: Ensure documentation is updated if needed
- 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?
Discord Community
Get real-time help from other contributors
GitHub Discussions
Ask questions and share ideas
GitHub Issues
Report bugs or request features
Development Setup
Set up your development environment
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! 🎉