Update Contributing
k.eaven committed
1 parent
572c793e70
commit
ed0b00f183
1 file changed
+374
-374
+374
-374
@@ -1,375 +1,375 @@
|
|||||||
# Contributing
|
# Contributing
|
||||||
|
|
||||||
## Overview
|
## 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.
|
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
|
## Development Setup
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
- Python 3.8+
|
- Python 3.8+
|
||||||
- Git
|
- Git
|
||||||
- Discord Developer Portal access (for testing)
|
- Discord Developer Portal access (for testing)
|
||||||
- Pterodactyl/Pelican Panel access (for testing)
|
- Pterodactyl/Pelican Panel access (for testing)
|
||||||
|
|
||||||
### Local Development Environment
|
### Local Development Environment
|
||||||
|
|
||||||
1. **Fork and clone the repository:**
|
1. **Fork and clone the repository:**
|
||||||
```bash
|
```bash
|
||||||
git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
|
git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
|
||||||
cd pterodactyl-discord-bot
|
cd pterodactyl-discord-bot
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Create a virtual environment:**
|
2. **Create a virtual environment:**
|
||||||
```bash
|
```bash
|
||||||
python -m venv venv
|
python -m venv venv
|
||||||
source venv/bin/activate # Linux/macOS
|
source venv/bin/activate # Linux/macOS
|
||||||
# venv\Scripts\activate # Windows
|
# venv\Scripts\activate # Windows
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **Install dependencies:**
|
3. **Install dependencies:**
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
pip install -r requirements-test.txt
|
pip install -r requirements-test.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Configure for development:**
|
4. **Configure for development:**
|
||||||
```bash
|
```bash
|
||||||
cp config.ini.sample config.ini
|
cp config.ini.sample config.ini
|
||||||
# Edit config.ini with your test credentials
|
# Edit config.ini with your test credentials
|
||||||
```
|
```
|
||||||
|
|
||||||
5. **Run tests:**
|
5. **Run tests:**
|
||||||
```bash
|
```bash
|
||||||
python -m pytest test_pterodisbot.py -v
|
python -m pytest test_pterodisbot.py -v
|
||||||
```
|
```
|
||||||
|
|
||||||
6. **Run the bot:**
|
6. **Run the bot:**
|
||||||
```bash
|
```bash
|
||||||
python main.py
|
python main.py
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
pterodactyl-discord-bot/
|
pterodactyl-discord-bot/
|
||||||
├── api.py # Pterodactyl/Pelican Panel API client
|
├── api.py # Pterodactyl/Pelican Panel API client
|
||||||
├── bot.py # Core bot, commands, background tasks
|
├── bot.py # Core bot, commands, background tasks
|
||||||
├── config.py # Configuration management
|
├── config.py # Configuration management
|
||||||
├── embeds.py # Embed creation, tracking, persistence
|
├── embeds.py # Embed creation, tracking, persistence
|
||||||
├── exceptions.py # Custom exception hierarchy
|
├── exceptions.py # Custom exception hierarchy
|
||||||
├── generate_config.py # Config generation from env vars
|
├── generate_config.py # Config generation from env vars
|
||||||
├── logging_config.py # Logging configuration
|
├── logging_config.py # Logging configuration
|
||||||
├── main.py # Entry point
|
├── main.py # Entry point
|
||||||
├── metrics.py # Metrics collection & graph generation
|
├── metrics.py # Metrics collection & graph generation
|
||||||
├── models.py # Pydantic data models
|
├── models.py # Pydantic data models
|
||||||
├── views.py # Discord UI components
|
├── views.py # Discord UI components
|
||||||
├── test_pterodisbot.py # Unit tests
|
├── test_pterodisbot.py # Unit tests
|
||||||
├── requirements.txt # Production dependencies
|
├── requirements.txt # Production dependencies
|
||||||
├── requirements-test.txt # Test dependencies
|
├── requirements-test.txt # Test dependencies
|
||||||
├── config.ini.sample # Sample configuration
|
├── config.ini.sample # Sample configuration
|
||||||
├── dockerfile # Docker build file
|
├── dockerfile # Docker build file
|
||||||
├── docker-compose.yml # Docker Compose
|
├── docker-compose.yml # Docker Compose
|
||||||
├── entrypoint.sh # Docker entry point
|
├── entrypoint.sh # Docker entry point
|
||||||
├── LICENSE # GPL-3.0 License
|
├── LICENSE # GPL-3.0 License
|
||||||
├── README.md # Project documentation
|
├── README.md # Project documentation
|
||||||
└── md_images/ # README images
|
└── md_images/ # README images
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Coding Standards
|
## Coding Standards
|
||||||
|
|
||||||
### Python Style
|
### Python Style
|
||||||
|
|
||||||
- **Formatter**: Black (line length 88)
|
- **Formatter**: Black (line length 88)
|
||||||
- **Linter**: Flake8
|
- **Linter**: Flake8
|
||||||
- **Type Checking**: MyPy
|
- **Type Checking**: MyPy
|
||||||
- **Import Sorting**: isort
|
- **Import Sorting**: isort
|
||||||
|
|
||||||
### Code Quality Commands
|
### Code Quality Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Format code
|
# Format code
|
||||||
black .
|
black .
|
||||||
|
|
||||||
# Lint
|
# Lint
|
||||||
flake8 .
|
flake8 .
|
||||||
|
|
||||||
# Type check
|
# Type check
|
||||||
mypy .
|
mypy .
|
||||||
|
|
||||||
# Sort imports
|
# Sort imports
|
||||||
isort .
|
isort .
|
||||||
```
|
```
|
||||||
|
|
||||||
### Documentation Standards
|
### Documentation Standards
|
||||||
|
|
||||||
- **Docstrings**: Google-style docstrings for all public functions/classes
|
- **Docstrings**: Google-style docstrings for all public functions/classes
|
||||||
- **Type Hints**: Required for all function signatures
|
- **Type Hints**: Required for all function signatures
|
||||||
- **Comments**: Explain "why", not "what"
|
- **Comments**: Explain "why", not "what"
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
```python
|
```python
|
||||||
async def get_server_resources(self, server_id: str) -> Dict[str, Any]:
|
async def get_server_resources(self, server_id: str) -> Dict[str, Any]:
|
||||||
"""Get resource usage for a specific server.
|
"""Get resource usage for a specific server.
|
||||||
|
|
||||||
Args:
|
Args:
|
||||||
server_id: The panel server identifier
|
server_id: The panel server identifier
|
||||||
|
|
||||||
Returns:
|
Returns:
|
||||||
Dictionary containing server resource usage and state
|
Dictionary containing server resource usage and state
|
||||||
|
|
||||||
Raises:
|
Raises:
|
||||||
ServerNotFoundError: If server doesn't exist
|
ServerNotFoundError: If server doesn't exist
|
||||||
APIError: For other API errors
|
APIError: For other API errors
|
||||||
"""
|
"""
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
### Running Tests
|
### Running Tests
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Run all tests
|
# Run all tests
|
||||||
python -m pytest test_pterodisbot.py -v
|
python -m pytest test_pterodisbot.py -v
|
||||||
|
|
||||||
# Run with coverage
|
# Run with coverage
|
||||||
python -m pytest test_pterodisbot.py --cov=. --cov-report=html
|
python -m pytest test_pterodisbot.py --cov=. --cov-report=html
|
||||||
|
|
||||||
# Run specific test
|
# Run specific test
|
||||||
python -m pytest test_pterodisbot.py::TestConfig::test_load_config -v
|
python -m pytest test_pterodisbot.py::TestConfig::test_load_config -v
|
||||||
```
|
```
|
||||||
|
|
||||||
### Test Structure
|
### Test Structure
|
||||||
|
|
||||||
Tests are organized in `test_pterodisbot.py`:
|
Tests are organized in `test_pterodisbot.py`:
|
||||||
- `TestConfig` - Configuration loading/validation
|
- `TestConfig` - Configuration loading/validation
|
||||||
- `TestPanelAPI` - API client functionality
|
- `TestPanelAPI` - API client functionality
|
||||||
- `TestEmbedManager` - Embed creation/tracking
|
- `TestEmbedManager` - Embed creation/tracking
|
||||||
- `TestMetrics` - Metrics collection/graphs
|
- `TestMetrics` - Metrics collection/graphs
|
||||||
- `TestViews` - Discord UI components
|
- `TestViews` - Discord UI components
|
||||||
|
|
||||||
### Writing Tests
|
### Writing Tests
|
||||||
|
|
||||||
- Use `pytest` framework
|
- Use `pytest` framework
|
||||||
- Mock external dependencies (Discord, Panel API)
|
- Mock external dependencies (Discord, Panel API)
|
||||||
- Test both success and failure paths
|
- Test both success and failure paths
|
||||||
- Follow AAA pattern (Arrange, Act, Assert)
|
- Follow AAA pattern (Arrange, Act, Assert)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Contribution Workflow
|
## Contribution Workflow
|
||||||
|
|
||||||
### 1. Find or Create an Issue
|
### 1. Find or Create an Issue
|
||||||
|
|
||||||
- Check [existing issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues)
|
- Check [existing issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues)
|
||||||
- Create new issue for bugs/features
|
- Create new issue for bugs/features
|
||||||
- Discuss approach before implementing large changes
|
- Discuss approach before implementing large changes
|
||||||
|
|
||||||
### 2. Create a Feature Branch
|
### 2. Create a Feature Branch
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git checkout -b feature/your-feature-name
|
git checkout -b feature/your-feature-name
|
||||||
# or
|
# or
|
||||||
git checkout -b fix/your-bug-fix
|
git checkout -b fix/your-bug-fix
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Make Changes
|
### 3. Make Changes
|
||||||
|
|
||||||
- Write code following coding standards
|
- Write code following coding standards
|
||||||
- Add/update tests
|
- Add/update tests
|
||||||
- Update documentation if needed
|
- Update documentation if needed
|
||||||
- Ensure all tests pass
|
- Ensure all tests pass
|
||||||
|
|
||||||
### 4. Commit Changes
|
### 4. Commit Changes
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git add .
|
git add .
|
||||||
git commit -m "feat: add new feature description"
|
git commit -m "feat: add new feature description"
|
||||||
# or
|
# or
|
||||||
git commit -m "fix: resolve issue description"
|
git commit -m "fix: resolve issue description"
|
||||||
```
|
```
|
||||||
|
|
||||||
**Commit Message Format:**
|
**Commit Message Format:**
|
||||||
- `feat:` - New feature
|
- `feat:` - New feature
|
||||||
- `fix:` - Bug fix
|
- `fix:` - Bug fix
|
||||||
- `docs:` - Documentation changes
|
- `docs:` - Documentation changes
|
||||||
- `refactor:` - Code refactoring
|
- `refactor:` - Code refactoring
|
||||||
- `test:` - Test additions/changes
|
- `test:` - Test additions/changes
|
||||||
- `chore:` - Maintenance tasks
|
- `chore:` - Maintenance tasks
|
||||||
|
|
||||||
### 5. Push and Create Pull Request
|
### 5. Push and Create Pull Request
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git push origin feature/your-feature-name
|
git push origin feature/your-feature-name
|
||||||
```
|
```
|
||||||
|
|
||||||
Then create a Pull Request on the Gitea repository.
|
Then create a Pull Request on the Gitea repository.
|
||||||
|
|
||||||
### 6. Code Review
|
### 6. Code Review
|
||||||
|
|
||||||
- Maintainers will review your PR
|
- Maintainers will review your PR
|
||||||
- Address feedback promptly
|
- Address feedback promptly
|
||||||
- Ensure CI passes (if configured)
|
- Ensure CI passes (if configured)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Areas for Contribution
|
## Areas for Contribution
|
||||||
|
|
||||||
### High Priority
|
### High Priority
|
||||||
|
|
||||||
- **Multi-guild support** - Currently single-guild only
|
- **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
|
- **Pelican Panel testing** - Verify compatibility
|
||||||
- **Additional metrics** - Disk I/O, network details
|
- **Additional metrics** - Disk I/O, network details
|
||||||
- **Web dashboard** - Optional web interface
|
- **Web dashboard** - Optional web interface
|
||||||
- **Database persistence** - SQLite/PostgreSQL for metrics history
|
- **Database persistence** - SQLite/PostgreSQL for metrics history
|
||||||
|
|
||||||
### Medium Priority
|
### Medium Priority
|
||||||
|
|
||||||
- **Slash command autocomplete** - Server name autocomplete
|
- **Slash command autocomplete** - Server name autocomplete
|
||||||
- **Scheduled tasks** - Auto-start/stop servers on schedule
|
- **Scheduled tasks** - Auto-start/stop servers on schedule
|
||||||
- **Notifications** - Discord alerts for server events
|
- **Notifications** - Discord alerts for server events
|
||||||
- **Localization** - Multi-language support
|
- **Localization** - Multi-language support
|
||||||
- **Plugin system** - Extensible architecture
|
- **Plugin system** - Extensible architecture
|
||||||
|
|
||||||
### Low Priority
|
### Low Priority
|
||||||
|
|
||||||
- **Code refactoring** - Improve internal structure
|
- **Code refactoring** - Improve internal structure
|
||||||
- **Performance optimization** - Reduce API calls
|
- **Performance optimization** - Reduce API calls
|
||||||
- **Additional graph types** - Historical trends
|
- **Additional graph types** - Historical trends
|
||||||
- **Mobile-friendly embeds** - Responsive layouts
|
- **Mobile-friendly embeds** - Responsive layouts
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Adding New Features
|
## Adding New Features
|
||||||
|
|
||||||
### 1. Discord Commands
|
### 1. Discord Commands
|
||||||
|
|
||||||
Add to `bot.py` in `setup_commands()`:
|
Add to `bot.py` in `setup_commands()`:
|
||||||
```python
|
```python
|
||||||
@bot.tree.command(
|
@bot.tree.command(
|
||||||
name="new_command",
|
name="new_command",
|
||||||
description="Description of command"
|
description="Description of command"
|
||||||
)
|
)
|
||||||
async def new_command(interaction: discord.Interaction) -> None:
|
async def new_command(interaction: discord.Interaction) -> None:
|
||||||
# Implementation
|
# Implementation
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. API Endpoints
|
### 2. API Endpoints
|
||||||
|
|
||||||
Add to `api.py` in `PanelAPI` class:
|
Add to `api.py` in `PanelAPI` class:
|
||||||
```python
|
```python
|
||||||
async def new_endpoint(self, param: str) -> Dict[str, Any]:
|
async def new_endpoint(self, param: str) -> Dict[str, Any]:
|
||||||
return await self._request("GET", f"endpoint/{param}")
|
return await self._request("GET", f"endpoint/{param}")
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Embed Fields
|
### 3. Embed Fields
|
||||||
|
|
||||||
Modify `embeds.py` in `EmbedManager.create_server_embed()`:
|
Modify `embeds.py` in `EmbedManager.create_server_embed()`:
|
||||||
```python
|
```python
|
||||||
def _add_new_field(self, embed: discord.Embed, data: Any) -> discord.Embed:
|
def _add_new_field(self, embed: discord.Embed, data: Any) -> discord.Embed:
|
||||||
# Add field logic
|
# Add field logic
|
||||||
return embed
|
return embed
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. Metrics
|
### 4. Metrics
|
||||||
|
|
||||||
Extend `metrics.py` in `ServerMetricsGraphs`:
|
Extend `metrics.py` in `ServerMetricsGraphs`:
|
||||||
```python
|
```python
|
||||||
def generate_new_graph(self) -> Optional[io.BytesIO]:
|
def generate_new_graph(self) -> Optional[io.BytesIO]:
|
||||||
# Graph generation logic
|
# Graph generation logic
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Reporting Bugs
|
## Reporting Bugs
|
||||||
|
|
||||||
### Bug Report Template
|
### Bug Report Template
|
||||||
|
|
||||||
**Description:** Clear description of the bug
|
**Description:** Clear description of the bug
|
||||||
|
|
||||||
**Steps to Reproduce:**
|
**Steps to Reproduce:**
|
||||||
1. Step one
|
1. Step one
|
||||||
2. Step two
|
2. Step two
|
||||||
3. Step three
|
3. Step three
|
||||||
|
|
||||||
**Expected Behavior:** What should happen
|
**Expected Behavior:** What should happen
|
||||||
|
|
||||||
**Actual Behavior:** What actually happens
|
**Actual Behavior:** What actually happens
|
||||||
|
|
||||||
**Environment:**
|
**Environment:**
|
||||||
- OS: [e.g., Ubuntu 22.04]
|
- OS: [e.g., Ubuntu 22.04]
|
||||||
- Python: [e.g., 3.11.2]
|
- Python: [e.g., 3.11.2]
|
||||||
- Discord.py: [e.g., 2.3.2]
|
- Discord.py: [e.g., 2.3.2]
|
||||||
- Pterodactyl Version: [e.g., 1.11.0]
|
- Pterodactyl Version: [e.g., 1.11.0]
|
||||||
|
|
||||||
**Logs:** Relevant log excerpts (remove sensitive data)
|
**Logs:** Relevant log excerpts (remove sensitive data)
|
||||||
|
|
||||||
**Screenshots:** If applicable
|
**Screenshots:** If applicable
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Feature Requests
|
## Feature Requests
|
||||||
|
|
||||||
### Feature Request Template
|
### Feature Request Template
|
||||||
|
|
||||||
**Feature:** Brief name/description
|
**Feature:** Brief name/description
|
||||||
|
|
||||||
**Problem:** What problem does this solve?
|
**Problem:** What problem does this solve?
|
||||||
|
|
||||||
**Solution:** Proposed implementation
|
**Solution:** Proposed implementation
|
||||||
|
|
||||||
**Alternatives:** Other approaches considered
|
**Alternatives:** Other approaches considered
|
||||||
|
|
||||||
**Additional Context:** Any other information
|
**Additional Context:** Any other information
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Code of Conduct
|
## Code of Conduct
|
||||||
|
|
||||||
This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/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
|
### Our Standards
|
||||||
|
|
||||||
- Be respectful and inclusive
|
- Be respectful and inclusive
|
||||||
- Welcome newcomers
|
- Welcome newcomers
|
||||||
- Focus on constructive feedback
|
- Focus on constructive feedback
|
||||||
- Accept responsibility for mistakes
|
- Accept responsibility for mistakes
|
||||||
|
|
||||||
### Enforcement
|
### Enforcement
|
||||||
|
|
||||||
Report violations to the project maintainers.
|
Report violations to the project maintainers.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
By contributing, you agree that your contributions will be licensed under the **GPL-3.0 License** (same as the project).
|
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.
|
See [LICENSE](../LICENSE) for full license text.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Getting Help
|
## Getting Help
|
||||||
|
|
||||||
- **Issues**: [Git Issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues)
|
- **Issues**: [Git Issues](https://git.serendipity.systems/k.eaven/pterodisbot/issues)
|
||||||
- **Discussions**: Use issue comments for discussion
|
- **Discussions**: Use issue comments for discussion
|
||||||
- **Documentation**: Check [README.md](../README.md) and wiki pages
|
- **Documentation**: Check [README.md](../README.md) and wiki pages
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Pages
|
## Related Pages
|
||||||
|
|
||||||
- [Architecture](/Architecture) - System design
|
- [Architecture](/Architecture) - System design
|
||||||
- [Installation](/Installation) - Deployment guides
|
- [Installation](/Installation) - Deployment guides
|
||||||
- [Configuration](/Configuration) - Config options
|
- [Configuration](/Configuration) - Config options
|
||||||
- [Usage](/Usage) - Commands and workflows
|
- [Usage](/Usage) - Commands and workflows
|
||||||
- [Features](/Features) - Feature details
|
- [Features](/Features) - Feature details
|
||||||
Reference in new issue
Block a user