Thank you for your interest in contributing to Pterodisbot! This project welcomes contributions from the community. This guide covers how to set up a development environment, coding standards, and the contribution process.

Development Setup

Prerequisites

Python 3.11+
Git
Discord Developer Portal access (for testing)
Pterodactyl/Pelican Panel access (for testing)

Local Development Environment

Fork and clone the repository:

git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
cd pterodactyl-discord-bot

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

Install dependencies:

pip install -r requirements.txt
pip install -r requirements-test.txt

Configure for development:

cp config.ini.sample config.ini
# Edit config.ini with your test credentials

Run tests:

python -m pytest test_pterodisbot.py -v

Run the bot:
```
python main.py
```

Project Structure

pterodactyl-discord-bot/
├── api.py                 # Pterodactyl/Pelican Panel API client
├── bot.py                 # Core bot, commands, background tasks
├── config.py              # Configuration management
├── embeds.py              # Embed creation, tracking, persistence
├── exceptions.py          # Custom exception hierarchy
├── generate_config.py     # Config generation from env vars
├── logging_config.py      # Logging configuration
├── main.py                # Entry point
├── metrics.py             # Metrics collection & graph generation
├── models.py              # Pydantic data models
├── views.py               # Discord UI components
├── test_pterodisbot.py    # Unit tests
├── requirements.txt       # Production dependencies
├── requirements-test.txt  # Test dependencies
├── config.ini.sample      # Sample configuration
├── dockerfile             # Docker build file
├── docker-compose.yml     # Docker Compose
├── entrypoint.sh          # Docker entry point
├── LICENSE                # GPL-3.0 License
├── README.md              # Project documentation
└── md_images/             # README images

Coding Standards

Python Style

Formatter: Black (line length 88)
Linter: Flake8
Type Checking: MyPy
Import Sorting: isort

Code Quality Commands

# Format code
black .

# Lint
flake8 .

# Type check
mypy .

# Sort imports
isort .

Documentation Standards

Docstrings: Google-style docstrings for all public functions/classes
Type Hints: Required for all function signatures
Comments: Explain "why", not "what"

Example:

async def get_server_resources(self, server_id: str) -> Dict[str, Any]:
    """Get resource usage for a specific server.

    Args:
        server_id: The panel server identifier

    Returns:
        Dictionary containing server resource usage and state

    Raises:
        ServerNotFoundError: If server doesn't exist
        APIError: For other API errors
    """

Testing

Running Tests

# Run all tests
python -m pytest test_pterodisbot.py -v

# Run with coverage
python -m pytest test_pterodisbot.py --cov=. --cov-report=html

# Run specific test
python -m pytest test_pterodisbot.py::TestConfig::test_load_config -v

Test Structure

Tests are organized in test_pterodisbot.py:

TestConfig - Configuration loading/validation
TestPanelAPI - API client functionality
TestEmbedManager - Embed creation/tracking
TestMetrics - Metrics collection/graphs
TestViews - Discord UI components

Writing Tests

Use pytest framework
Mock external dependencies (Discord, Panel API)
Test both success and failure paths
Follow AAA pattern (Arrange, Act, Assert)

Contribution Workflow

1. Find or Create an Issue

Check existing issues
Create new issue for bugs/features
Discuss approach before implementing large changes

2. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

3. Make Changes

Write code following coding standards
Add/update tests
Update documentation if needed
Ensure all tests pass

4. Commit Changes

git add .
git commit -m "feat: add new feature description"
# or
git commit -m "fix: resolve issue description"

Commit Message Format:

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

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a Pull Request on the Gitea repository.

6. Code Review

Maintainers will review your PR
Address feedback promptly
Ensure CI passes (if configured)

Areas for Contribution

High Priority

Multi-guild support - In the scenario admins manage multiple Discord guilds they want the bot to be used in simultaneously
Pelican Panel testing - Verify compatibility
Additional metrics - Disk I/O, network details
Web dashboard - Optional web interface
Database persistence - SQLite/PostgreSQL for metrics history

Medium Priority

Slash command autocomplete - Server name autocomplete
Scheduled tasks - Auto-start/stop servers on schedule
Notifications - Discord alerts for server events
Localization - Multi-language support
Plugin system - Extensible architecture

Low Priority

Code refactoring - Improve internal structure
Performance optimization - Reduce API calls
Additional graph types - Historical trends
Mobile-friendly embeds - Responsive layouts

Adding New Features

1. Discord Commands

Add to bot.py in setup_commands():

@bot.tree.command(
    name="new_command",
    description="Description of command"
)
async def new_command(interaction: discord.Interaction) -> None:
    # Implementation

2. API Endpoints

Add to api.py in PanelAPI class:

async def new_endpoint(self, param: str) -> Dict[str, Any]:
    return await self._request("GET", f"endpoint/{param}")

3. Embed Fields

Modify embeds.py in EmbedManager.create_server_embed():

def _add_new_field(self, embed: discord.Embed, data: Any) -> discord.Embed:
    # Add field logic
    return embed

4. Metrics

Extend metrics.py in ServerMetricsGraphs:

def generate_new_graph(self) -> Optional[io.BytesIO]:
    # Graph generation logic

Reporting Bugs

Bug Report Template

Description: Clear description of the bug

Steps to Reproduce:

Step one
Step two
Step three

Expected Behavior: What should happen

Actual Behavior: What actually happens

Environment:

OS: [e.g., Ubuntu 22.04]
Python: [e.g., 3.11.2]
Discord.py: [e.g., 2.3.2]
Pterodactyl Version: [e.g., 1.11.0]

Logs: Relevant log excerpts (remove sensitive data)

Screenshots: If applicable

Feature Requests

Feature Request Template

Feature: Brief name/description

Problem: What problem does this solve?

Solution: Proposed implementation

Alternatives: Other approaches considered

Additional Context: Any other information

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

Our Standards

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Accept responsibility for mistakes

Enforcement

Report violations to the project maintainers.

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License (same as the project).

See LICENSE for full license text.

Getting Help

Issues: Git Issues
Discussions: Use issue comments for discussion
Documentation: Check README.md and wiki pages

Architecture - System design
Installation - Deployment guides
Configuration - Config options
Usage - Commands and workflows
Features - Feature details

Contributing

Overview