diff --git a/Contributing.md b/Contributing.md index d468bb1..aa0b79a 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1,375 +1,375 @@ -# Contributing - -## Overview - -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.8+ -- Git -- Discord Developer Portal access (for testing) -- Pterodactyl/Pelican Panel access (for testing) - -### Local Development Environment - -1. **Fork and clone the repository:** - ```bash - git clone https://git.serendipity.systems/k.eaven/pterodisbot.git - cd pterodactyl-discord-bot - ``` - -2. **Create a virtual environment:** - ```bash - python -m venv venv - source venv/bin/activate # Linux/macOS - # venv\Scripts\activate # Windows - ``` - -3. **Install dependencies:** - ```bash - pip install -r requirements.txt - pip install -r requirements-test.txt - ``` - -4. **Configure for development:** - ```bash - cp config.ini.sample config.ini - # Edit config.ini with your test credentials - ``` - -5. **Run tests:** - ```bash - python -m pytest test_pterodisbot.py -v - ``` - -6. **Run the bot:** - ```bash - 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 - -```bash -# 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: -```python -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 - -```bash -# 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](https://git.serendipity.systems/k.eaven/pterodisbot/issues) -- Create new issue for bugs/features -- Discuss approach before implementing large changes - -### 2. Create a Feature Branch - -```bash -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 - -```bash -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 - -```bash -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** - Currently single-guild only -- **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()`: -```python -@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: -```python -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()`: -```python -def _add_new_field(self, embed: discord.Embed, data: Any) -> discord.Embed: - # Add field logic - return embed -``` - -### 4. Metrics - -Extend `metrics.py` in `ServerMetricsGraphs`: -```python -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:** -1. Step one -2. Step two -3. 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](https://www.contributor-covenant.org/version/2/1/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](../LICENSE) for full license text. - ---- - -## Getting Help - -- **Issues**: [Git Issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues) -- **Discussions**: Use issue comments for discussion -- **Documentation**: Check [README.md](../README.md) and wiki pages - ---- - -## Related Pages - -- [Architecture](/Architecture) - System design -- [Installation](/Installation) - Deployment guides -- [Configuration](/Configuration) - Config options -- [Usage](/Usage) - Commands and workflows +# Contributing + +## Overview + +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.8+ +- Git +- Discord Developer Portal access (for testing) +- Pterodactyl/Pelican Panel access (for testing) + +### Local Development Environment + +1. **Fork and clone the repository:** + ```bash + git clone https://git.serendipity.systems/k.eaven/pterodisbot.git + cd pterodactyl-discord-bot + ``` + +2. **Create a virtual environment:** + ```bash + python -m venv venv + source venv/bin/activate # Linux/macOS + # venv\Scripts\activate # Windows + ``` + +3. **Install dependencies:** + ```bash + pip install -r requirements.txt + pip install -r requirements-test.txt + ``` + +4. **Configure for development:** + ```bash + cp config.ini.sample config.ini + # Edit config.ini with your test credentials + ``` + +5. **Run tests:** + ```bash + python -m pytest test_pterodisbot.py -v + ``` + +6. **Run the bot:** + ```bash + 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 + +```bash +# 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: +```python +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 + +```bash +# 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](https://git.serendipity.systems/k.eaven/pterodisbot/issues) +- Create new issue for bugs/features +- Discuss approach before implementing large changes + +### 2. Create a Feature Branch + +```bash +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 + +```bash +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 + +```bash +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()`: +```python +@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: +```python +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()`: +```python +def _add_new_field(self, embed: discord.Embed, data: Any) -> discord.Embed: + # Add field logic + return embed +``` + +### 4. Metrics + +Extend `metrics.py` in `ServerMetricsGraphs`: +```python +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:** +1. Step one +2. Step two +3. 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](https://www.contributor-covenant.org/version/2/1/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](../LICENSE) for full license text. + +--- + +## Getting Help + +- **Issues**: [Git Issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues) +- **Discussions**: Use issue comments for discussion +- **Documentation**: Check [README.md](../README.md) and wiki pages + +--- + +## Related Pages + +- [Architecture](/Architecture) - System design +- [Installation](/Installation) - Deployment guides +- [Configuration](/Configuration) - Config options +- [Usage](/Usage) - Commands and workflows - [Features](/Features) - Feature details \ No newline at end of file