likwid/CONTRIBUTING.md

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

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

# Copy environment configuration
cp .env.example .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

cd backend
cargo fmt --check
cargo clippy

TypeScript (Frontend)

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

cd frontend
npm run check

Testing

# Backend tests
cd backend
cargo test

# Frontend checks
cd frontend
npm run check

Database Migrations

We use SQLx for compile-time checked queries:

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 LGPL-2.1-or-later.

---