# Contributing to Likwid

## Getting Started

### Development Environment

#### Prerequisites

**All Platforms:**
- Git
- Rust (via rustup) — latest stable
- Node.js LTS (20.x+)
- Podman (for database)

**Windows:**
- WSL2 enabled
- Podman Desktop with WSL2 backend
- MSVC toolchain for Rust

**Linux:**
- podman-compose

### Quick Setup

```bash
# Clone the repository
git clone https://codeberg.org/likwid/likwid
cd likwid

# Copy environment configuration
cp backend/.env.example backend/.env

# Start development environment
# Windows:
.\scripts\dev-start.ps1

# Linux:
./scripts/dev-start.sh
```

### Project Structure

```
likwid/
├── backend/           # Rust backend (Axum)
│   ├── src/
│   │   ├── api/       # HTTP endpoints
│   │   ├── auth/      # Authentication
│   │   ├── models/    # Database models
│   │   └── plugins/   # Plugin system
│   └── migrations/    # SQLx migrations
├── frontend/          # Astro frontend
│   └── src/
│       ├── pages/     # Routes
│       ├── layouts/   # Page templates
│       └── components/# Reusable UI
├── scripts/           # Dev scripts
└── compose/           # Container configs
```

## Development Workflow

### Branch Naming

- `feature/description` — New features
- `fix/description` — Bug fixes
- `docs/description` — Documentation
- `refactor/description` — Code refactoring

```
type(scope): description

[optional body]

[optional footer]
```

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

**Examples:**
```
feat(voting): implement Schulze method
fix(auth): correct JWT expiration handling
docs(readme): add Voting System info
```

### Code Style

#### Rust (Backend)

- Follow `rustfmt` defaults
- Use `clippy` for linting
- Document public APIs with `///` comments
- Prefer `Result<T, E>` over panics

```bash
cd backend
cargo fmt --check
cargo clippy
```

#### TypeScript (Frontend)

- Strict mode enabled
- Use TypeScript for all new code
- Follow Astro conventions

```bash
cd frontend
npm run check
```

### Testing

```bash
# Backend tests
cd backend
cargo test

# Frontend checks
cd frontend
npm run check
```

### Database Migrations

We use SQLx for compile-time checked queries:

```bash
cd backend

# Create a new migration
sqlx migrate add description_of_change

# Run migrations
sqlx migrate run

# Prepare offline query data (for CI)
cargo sqlx prepare
```

## Contributing Guidelines

### Before You Start

1. **Check existing issues** — Someone may already be working on it
2. **Open an issue first** — For significant changes, discuss before coding
3. **Keep changes focused** — One feature/fix per merge request

### Submitting Changes

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure tests pass
5. Submit a merge request

### Merge Request Checklist

- [ ] Code follows project style
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Commit messages follow conventions
- [ ] No unrelated changes


### Find a Third Way

When opinions conflict, seek solutions that satisfy everyone rather than taking sides. The best outcomes come from understanding all perspectives.

### Be Pragmatic

We value tangible results over theoretical debates. If something works and improves the project, it's worth considering.

### Support Each Other

Help newcomers, answer questions patiently, and remember that everyone was new once.

## Areas for Contribution

### High Priority
- Advanced voting methods (Schulze, STAR, Quadratic)
- Liquid delegation engine
- Accessibility improvements
- Mobile responsiveness
- Internationalization (i18n)

### Plugin Development
- Create new plugins for the WASM runtime
- Improve plugin documentation
- Build integrations (GitLab, Matrix, etc.)

### Documentation
- User guides
- API documentation
- Tutorial videos
- Translations

### Design
- UI/UX improvements
- Icon design
- Theme development

## License

By contributing, you agree that your contributions will be licensed under EUPL-1.2.

---