Contributing Guidelines

Welcome Contributors!

We appreciate contributions of all kinds to Obsidian Chess Studio. Whether you’re fixing bugs, adding features, improving documentation, or translating the app, your contributions are valuable.

Before You Start

Check Existing Issues

Before starting work, check the issues page to see if:

Someone else is already working on it
There’s a discussion about the feature/bug
Maintainers have provided guidance

If unsure, open an issue first to discuss your idea.

Read the Documentation

Familiarize yourself with:

Join the Community

GitHub Discussions: Ask questions and share ideas
Issues: Report bugs and request features
Stay updated with project direction

Development Workflow

1. Fork and Clone

Fork the Repository

Click the “Fork” button on GitHub

Clone Your Fork

git clone [email protected]:{your_username}/Obsidian-Chess-Studio.git
cd Obsidian-Chess-Studio

Add Upstream Remote

git remote add upstream [email protected]:luisrivasnoriega/Obsidian-Chess-Studio.git

2. Create a Feature Branch

Always create a new branch from master for your work:

# Update master
git checkout master
git pull upstream master

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

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
refactor/ - Code refactoring
docs/ - Documentation changes
test/ - Test additions/fixes

3. Install Dependencies

pnpm install

4. Make Your Changes

Now you can start coding! See the sections below for specific guidelines.

Code Style

Frontend (TypeScript/React)

Formatting
Linting
React Patterns
State Management

Use Biome for code formatting:

# Format all files
pnpm format

# Check formatting
pnpm biome check ./src

Settings:

Indentation: 2 spaces
Quotes: Double quotes
Semicolons: Required
Trailing commas: ES5

Fix linting issues before committing:

# Lint and auto-fix
pnpm lint:fix

# Check types
pnpm lint

Rules:

Strict TypeScript checking
No unused variables
Consistent naming (camelCase)
Prefer const over let

Component structure:

// Use named exports
export function MyComponent({ prop }: MyComponentProps) {
  // Hooks at the top
  const [state, setState] = useState(initialValue);
  const theme = useMantineTheme();
  
  // Event handlers
  const handleClick = useCallback(() => {
    // ...
  }, [dependencies]);
  
  // Render
  return (
    <div>
      {/* JSX */}
    </div>
  );
}

Prefer:

Functional components over class components
useCallback for event handlers
useMemo for expensive computations
TypeScript interfaces for props

Use the right tool:

Jotai atoms for global state (src/state/atoms.ts)
Zustand stores for complex state (src/state/store/)
useState for local component state
TanStack Router for URL state

Example:

// Jotai atom
import { useAtom } from 'jotai';
import { tabsAtom } from '@/state/atoms';

function MyComponent() {
  const [tabs, setTabs] = useAtom(tabsAtom);
  // ...
}

Backend (Rust)

Formatting
Linting
Error Handling
Tauri Commands

Use rustfmt for formatting:

cd src-tauri
cargo fmt

Settings:

4-space indentation
100-character line limit
Trailing commas

Use clippy for linting:

cd src-tauri
cargo clippy -- -D warnings

Fix all clippy warnings before submitting.

Use the custom error type:

use crate::error::Error;

#[tauri::command]
pub fn my_command() -> Result<Data, Error> {
    let result = risky_operation()
        .map_err(Error::from)?;
    
    Ok(result)
}

Error types in src-tauri/src/error.rs:

Error::Database - Database errors
Error::FileSystem - File I/O errors
Error::Parse - Parsing errors
Error::Engine - Chess engine errors

Command structure:

#[tauri::command]
#[specta::specta]  // For TypeScript bindings
pub async fn my_async_command(
    app: tauri::AppHandle,
    param: String,
) -> Result<ReturnType, Error> {
    // Implementation
    Ok(result)
}

Guidelines:

Use async for I/O operations
Return Result<T, Error> for error handling
Add #[specta::specta] for TypeScript bindings
Document with /// comments

Testing

Frontend Tests

Write Tests

Add tests in __tests__/ directories:

// src/features/boards/__tests__/BoardGame.test.tsx
import { render, screen } from '@testing-library/react';
import { BoardGame } from '../components/BoardGame';

describe('BoardGame', () => {
  it('renders chess board', () => {
    render(<BoardGame />);
    expect(screen.getByRole('main')).toBeInTheDocument();
  });
});

Run Tests

# Run all tests
pnpm test

# Run with coverage
pnpm vitest run --coverage

# Watch mode
pnpm vitest

Backend Tests

Write Tests

Add tests in module files:

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_position_search() {
        let fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
        let result = search_position(fen, true);
        assert!(result.is_ok());
    }
}

Run Tests

cd src-tauri

# Run all tests
cargo test

# Run specific test
cargo test test_position_search

# Run with output
cargo test -- --nocapture

See Testing Guide for comprehensive coverage.

Submitting a Pull Request

Ensure Quality

Before submitting, verify:

Build Check
Format & Lint
Run Tests

# Build without bundling installer
pnpm tauri build -b none

# Test the build
./src-tauri/target/release/obsidian-chess-studio

# Format frontend
pnpm format

# Lint frontend
pnpm lint:fix

# Format backend
cd src-tauri && cargo fmt

# Lint backend
cargo clippy -- -D warnings

# Frontend tests
pnpm test

# Backend tests
cd src-tauri && cargo test

Commit Changes

Write clear commit messages:

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add position search caching"

Commit message format:

feat: - New feature
fix: - Bug fix
refactor: - Code refactoring
docs: - Documentation changes
test: - Test additions/fixes
chore: - Build/tooling changes

Push to Fork

git push origin feature/your-feature-name

Create Pull Request

Go to the comparison page
Select your fork and branch in the compare: dropdown
Click “Create pull request”
Fill in the PR template:
- Title: Clear, descriptive title
- Description: What changes were made and why
- Testing: How you tested the changes
- Screenshots: For UI changes
- Related issues: Link to issues this PR addresses

Address Review Feedback

Maintainers will review your PR. Address any feedback:

# Make changes based on feedback
git add .
git commit -m "refactor: address review feedback"
git push origin feature/your-feature-name

PR Checklist

Before submitting, ensure:

Code builds successfully (pnpm tauri build -b none)
All tests pass (pnpm test and cargo test)
Code is formatted (pnpm format and cargo fmt)
No linting errors (pnpm lint:fix and cargo clippy)
Commit messages follow convention
PR description is clear and complete
Screenshots included for UI changes
Documentation updated if needed

Contributing Translations

See the dedicated Translations Guide for:

Adding new languages
Updating existing translations
Testing translations
Translation workflow

Code Review Process

Initial Review

Maintainers will review your PR within 1-3 days.

Feedback

You may receive:

Requested changes - Required before merge
Suggestions - Optional improvements
Questions - Clarifications needed

Approval

Once approved, maintainers will merge your PR.

Post-Merge

Your changes will be included in the next release!

Getting Help

If you need assistance:

GitHub Discussions

Ask questions and get help from the community

Issues

Report bugs or request features

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.

Next Steps

Development Overview

Learn about the tech stack

Testing Guide

Write comprehensive tests

Architecture

Understand the codebase

Translations

Help localize the app

Getting Started

Contributing

Architecture

Welcome Contributors!

Before You Start

Development Workflow

1. Fork and Clone

2. Create a Feature Branch

3. Install Dependencies

4. Make Your Changes

Code Style

Frontend (TypeScript/React)

Backend (Rust)

Testing

Frontend Tests

Backend Tests

Submitting a Pull Request

PR Checklist

Contributing Translations

Code Review Process

Getting Help

GitHub Discussions

Issues

License

Next Steps

Development Overview

Testing Guide

Architecture

Translations

Build docs developers (and LLMs) love

Getting Started

Contributing

Architecture

​Welcome Contributors!

​Before You Start

​Development Workflow

​1. Fork and Clone

​2. Create a Feature Branch

​3. Install Dependencies

​4. Make Your Changes

​Code Style

​Frontend (TypeScript/React)

​Backend (Rust)

​Testing

​Frontend Tests

​Backend Tests

​Submitting a Pull Request

​PR Checklist

​Contributing Translations

​Code Review Process

​Getting Help

GitHub Discussions

Issues

​License

​Next Steps

Development Overview

Testing Guide

Architecture

Translations

Build docs developers (and LLMs) love

Welcome Contributors!

Before You Start

Development Workflow

1. Fork and Clone

2. Create a Feature Branch

3. Install Dependencies

4. Make Your Changes

Code Style

Frontend (TypeScript/React)

Backend (Rust)

Testing

Frontend Tests

Backend Tests

Submitting a Pull Request

PR Checklist

Contributing Translations

Code Review Process

Getting Help

License

Next Steps