#Contributing to Palpo

Thank you for your interest in contributing to Palpo! We welcome contributions from everyone, whether you're fixing bugs, adding features, improving documentation, or writing tests.

#Table of Contents

• Getting Started
• Development Setup
• Making Contributions
• Code Style
• Testing
• Pull Request Process
• Reporting Issues

#Getting Started

Before contributing, please:

1. Read this guide in full
2. Check existing issues to avoid duplicates
3. For significant changes, open an issue first to discuss your proposal

#Development Setup

#Prerequisites

• Rust 1.94+ - Install via rustup
• PostgreSQL 17+ - Required for the database backend
• System dependencies (Linux):

  sudo apt install -y libclang-dev libpq-dev cmake

#Building from Source

# Clone the repository
git clone https://github.com/palpo-im/palpo.git
cd palpo

# Build the project
cargo build

# Run all checks (recommended before committing)
cargo check --all --bins --examples --tests

#Admin Console

Palpo includes an interactive admin console for managing the server:

# Console-only mode (no HTTP server)
./palpo -c palpo.toml -s false --console

# Console + server mode
./palpo -c palpo.toml --console

Console commands:

Keyboard shortcuts:

Graceful shutdown:

When running in console+server mode, exiting the console (via exit, quit, or Ctrl+D) triggers a graceful server shutdown. The server will stop accepting new connections and exit cleanly.

When running as a daemon (without --console), send SIGTERM or SIGQUIT for graceful shutdown:

kill -TERM <palpo-pid>

#Project Structure

Palpo is organized as a Cargo workspace with the following crates:

#Making Contributions

#Types of Contributions

We appreciate all kinds of contributions:

• Bug fixes - Fix issues reported in the tracker
• Features - Implement new functionality (discuss first in an issue)
• Documentation - Improve docs, add examples, fix typos
• Tests - Add test coverage, improve existing tests
• Performance - Optimize code, reduce memory usage

#Before You Start

1. Create a branch from main for your work
2. Keep changes focused - One logical change per PR
3. Write tests for new functionality
4. Update documentation if needed

#Code Style

#Rust Formatting

We use rustfmt with the Rust 2024 edition style. Format your code before committing:

cargo +nightly fmt --all

#Linting

We use clippy for linting. Your code should pass without warnings:

cargo clippy --all --all-features -- -D warnings

#Spell Checking

We use typos to catch spelling mistakes:

# Install typos
cargo install typos-cli

# Run spell check
typos

#Style Guidelines

• Use meaningful variable and function names
• Keep functions focused and reasonably sized
• Add comments for complex logic (not obvious code)
• Follow existing patterns in the codebase
• Prefer explicit error handling over .unwrap() in production code

#Testing

#Running Tests

# Run all tests
cargo test --all --all-features

# Run tests for a specific crate
cargo test -p palpo-core

# Run a specific test
cargo test test_name

#Complement Testing

We use Complement for Matrix specification compliance testing. See the tests/README.md for details.

#Writing Tests

• Add unit tests for new functions and modules
• Add integration tests for API endpoints
• Test both success and error cases
• Use descriptive test names that explain what is being tested

#Pull Request Process

#Before Submitting

Ensure your changes pass all CI checks locally:

# Format check
cargo fmt --all -- --check

# Linting
cargo clippy --all --all-features -- -D warnings

# Build check
cargo check --all --bins --examples --tests

# Tests
cargo test --all --all-features --no-fail-fast

# Spell check
typos

#Submitting a PR

1. Create a descriptive title - Summarize the change clearly
2. Write a helpful description - Explain what and why
3. Reference related issues - Use Fixes #123 or Relates to #123
4. Keep it reviewable - Smaller PRs are easier to review and merge

#PR Title Format

Use a clear, descriptive title:

• fix: resolve login failure on invalid tokens
• feat: add support for room aliases
• docs: update installation guide
• refactor: simplify event handling logic
• test: add tests for federation endpoints

#Review Process

• A maintainer will review your PR
• Address feedback and update your PR as needed
• Once approved, a maintainer will merge your PR

#Reporting Issues

#Bug Reports

Use the bug report template and include:

• Palpo version or git SHA
• Whether you're running in Docker
• Client used (if applicable)
• Clear description of the problem
• Steps to reproduce

#Feature Requests

Use the feature request template and:

• Describe the feature clearly
• Explain the use case
• Note: Don't request missing Matrix spec features as issues

#Questions?

• Check existing issues and discussions
• Open a new issue for questions about contributing

Thank you for contributing to Palpo!