discord_bot/DEVELOPMENT.md

Fjerkroa Bot Development Guide

This document outlines the development setup and workflows for the Fjerkroa Bot project.

Development Tools Setup

Prerequisites

• Python 3.11 (required - use python3.11 and pip3.11 explicitly)
• Git

Quick Start

# Install development dependencies
make install-dev

# Or manually:
pip3.11 install -r requirements.txt
pip3.11 install -e .
pre-commit install

Available Development Commands

Use the Makefile for all development tasks. Run make help to see all available commands:

Installation

• make install - Install production dependencies
• make install-dev - Install development dependencies and pre-commit hooks

Code Quality

• make lint - Run linter (flake8)
• make format - Format code with black and isort
• make format-check - Check if code is properly formatted
• make type-check - Run type checker (mypy)
• make security-check - Run security scanner (bandit)

Testing

• make test - Run tests
• make test-fast - Run tests without slow tests
• make test-cov - Run tests with coverage report

Combined Operations

• make all-checks - Run all code quality checks and tests
• make pre-commit - Run all pre-commit checks (format, then check)
• make ci - Full CI pipeline (install deps and run all checks)

Utility

• make clean - Clean up temporary files and caches
• make run - Run the bot (requires config.toml)
• make run-dev - Run the bot in development mode with auto-reload

Tool Configuration

All development tools are configured via pyproject.toml and .flake8:

Code Formatting (Black + isort)

• Line length: 140 characters
• Target Python version: 3.8+
• Imports sorted and formatted consistently

Linting (Flake8)

• Max line length: 140
• Max complexity: 10
• Ignores: E203, E266, E501, W503, E306 (for Black compatibility)

Type Checking (MyPy)

• Strict type checking enabled
• Checks both fjerkroa_bot and tests directories
• Ignores missing imports for external libraries

Security Scanning (Bandit)

• Scans for security issues
• Skips known safe patterns (pickle, random) for this application

Testing (Pytest)

• Configured for async tests
• Coverage reporting available
• Markers for slow tests

Pre-commit Hooks

Pre-commit hooks are automatically installed with make install-dev. They run:

1. Built-in checks (trailing whitespace, file endings, etc.)
2. Black code formatter
3. isort import sorter
4. Flake8 linter
5. Bandit security scanner
6. MyPy type checker
7. Fast tests

To run pre-commit manually:

pre-commit run --all-files

Development Workflow

1. Setup: Run make install-dev
2. Development: Make your changes
3. Check: Run make pre-commit to format and check code
4. Test: Run make test or make test-cov for coverage
5. Commit: Git will automatically run pre-commit hooks

Continuous Integration

The make ci command runs the complete CI pipeline:

• Installs all dependencies
• Runs linting (flake8)
• Checks formatting (black, isort)
• Runs type checking (mypy)
• Runs security scanning (bandit)
• Runs all tests

File Structure

fjerkroa_bot/
├── fjerkroa_bot/           # Main package
├── tests/                  # Test files
├── requirements.txt        # Production dependencies
├── pyproject.toml         # Tool configuration
├── .flake8               # Flake8 configuration
├── .pre-commit-config.yaml # Pre-commit configuration
├── Makefile              # Development commands
└── setup.py              # Package setup

Adding Dependencies

1. Add to requirements.txt for production dependencies
2. Add to pyproject.toml for development dependencies
3. Run make install-dev to install

Troubleshooting

Pre-commit Issues

# Reset pre-commit
pre-commit clean
pre-commit install

Tool Not Found Errors

Ensure you're using python3.11 and pip3.11 explicitly, and that all dependencies are installed:

make install-dev

Type Check Errors

Install missing type stubs:

pip3.11 install types-requests types-toml