Update "Contributing"
k.eaven committed
1 parent
b2c775d992
commit
4cc177b4a8
1 file changed
+375
+375
@@ -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
|
||||
Reference in new issue
Block a user