From 4cc177b4a8568f1d61346c2509df6b43f19eee20 Mon Sep 17 00:00:00 2001 From: Eaven Kimura Date: Mon, 26 Oct 2026 12:10:23 +0000 Subject: [PATCH] Update "Contributing" --- Contributing.md | 375 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) diff --git a/Contributing.md b/Contributing.md index e69de29..d468bb1 100644 --- a/Contributing.md +++ b/Contributing.md @@ -0,0 +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 +- [Features](/Features) - Feature details \ No newline at end of file