For Developers

Welcome to Tux development! This guide will help you set up your development environment and make your first contribution.

What You'll Need

Required

Python 3.13+ - The minimum supported version
UV - Fast Python package manager
PostgreSQL - Database (can use Docker)
Git - Version control
Discord Bot Application - For testing

Quick Setup

1. Clone and Install

# Clone the repository
git clone https://github.com/allthingslinux/tux.git
cd tux

# Install UV if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all dependencies (including dev, test, docs)
uv sync

# Set up pre-commit hooks
uv run pre-commit install

2. Configure Environment

# Copy example environment
cp .env.example .env

# Edit with your bot token and database settings
nano .env

Minimum required settings:

# Your Discord bot token
BOT_TOKEN=your_test_bot_token

# Database connection
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=tuxdb
POSTGRES_USER=tuxuser
POSTGRES_PASSWORD=devpassword123

# Enable debug mode for development
DEBUG=true

3. Set Up Database

Option A: Using Docker (Recommended)

# Start PostgreSQL with Docker Compose
uv run docker up

# This starts postgres + adminer web UI
# Access adminer at http://localhost:8080

Option B: Local PostgreSQL

# Create database and user
createdb tuxdb
createuser tuxuser

# Set password and grant permissions
psql -c "ALTER USER tuxuser PASSWORD 'devpassword123';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE tuxdb TO tuxuser;"

4. Run Migrations

# Initialize database with migrations
uv run db push

5. Start Development Bot

# Start with hot-reload enabled
uv run tux start --debug

# Bot will automatically reload when you change code!

Development Workflow

Running Code Quality Checks

# Run all checks at once
uv run dev all

# Or run individually:
uv run dev lint           # Ruff linter
uv run dev format         # Ruff formatter
uv run dev type-check     # Basedpyright
uv run dev lint-docstring # Pydoclint

Running Tests

# Run all tests with coverage
uv run tests run

# Quick run without coverage
uv run tests quick

# Run specific test file
uv run pytest tests/unit/test_config_loaders.py

# Run with specific marker
uv run pytest -m unit

Full Testing Guide →

Database Operations

# Create new migration
uv run db new "add user preferences"

# Apply migrations
uv run db push

# Check migration status
uv run db status

# View database tables
uv run db tables

# Reset database (safe, uses migrations)
uv run db reset

Database Guide →

Building Documentation

# Serve docs locally with hot-reload
uv run docs serve

# Build static docs
uv run docs build

# Access at http://localhost:8000

Project Structure

Understanding the codebase layout:

tux/
├── src/tux/              # Main source code
│   ├── core/             # Core bot functionality
│   ├── database/         # Database models & controllers
│   ├── modules/          # Command modules (cogs)
│   ├── services/         # Service layer (wrappers, handlers)
│   ├── ui/               # UI components (embeds, views, modals)
│   └── shared/           # Shared utilities & config
├── scripts/              # CLI tools (db, dev, tests, etc.)
├── tests/                # Test suite
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── e2e/              # End-to-end tests
├── docs/                 # Documentation
└── pyproject.toml        # Project configuration

Detailed Project Structure →

Making Your First Contribution

1. Choose What to Work On

Good First Issues - Beginner-friendly
Help Wanted - Community priority
Bug Reports - Fix bugs

2. Create a Branch

# Create feature branch
git checkout -b feature/your-feature-name

# Or bugfix branch
git checkout -b fix/bug-description

3. Make Your Changes

Follow our coding standards:

Type hints on all functions
Numpy-style docstrings for documentation
Async/await patterns for I/O operations
Controller pattern for database access
No print statements (use loguru logger)

Code Standards Guide →

4. Test Your Changes

# Run relevant tests
uv run tests run

# Run code quality checks
uv run dev all

# Test the bot manually in Discord
uv run tux start --debug

5. Commit Your Changes

We use Conventional Commits:

git add .
git commit -m "feat: add user preferences command"
# OR
git commit -m "fix: resolve database connection timeout"

Commit types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
refactor: - Code refactoring
test: - Test changes
chore: - Maintenance tasks

6. Push and Create PR

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub
# Fill out the PR template with details

Full Contribution Guide →

Essential Developer Resources

Architecture Documentation

Architecture Overview - System design
Bot Lifecycle - Startup/shutdown
Cog System - Module system
Permission System - Dynamic permissions

Development Guides

Creating a Cog - Add new modules
Creating Commands - Hybrid commands
Database Operations - Using controllers
UI Components - Views, modals, buttons

Patterns & Best Practices

Database Patterns - Controller pattern, DI
Error Handling - Error patterns
Async Patterns - Async best practices

Development Tools

CLI Commands

All development tasks use our custom CLI:

# Bot management
uv run tux start         # Start bot
uv run tux start --debug # Start with debug mode
uv run tux version       # Show version

# Database management
uv run db push           # Apply migrations
uv run db new "msg"      # Create migration
uv run db status         # Check status
uv run db health         # Health check

# Development tools
uv run dev lint          # Lint code
uv run dev format        # Format code
uv run dev type-check    # Type checking
uv run dev all           # All checks

# Testing
uv run tests run         # Run tests
uv run tests quick       # Quick run
uv run tests coverage    # Coverage report

# Docker
uv run docker up         # Start services
uv run docker down       # Stop services
uv run docker logs       # View logs

# Documentation
uv run docs serve        # Serve docs
uv run docs build        # Build docs

CLI Tools Guide →

Hot Reload

Tux includes automatic hot-reload for development:

Edit any Python file
Save the file
Tux automatically reloads the changed module
No need to restart the bot!

Hot Reload System →

Debugging

# Use loguru for logging
from loguru import logger

logger.debug("Debug information")
logger.info("Information")
logger.warning("Warning")
logger.error("Error occurred")