Update Contributing Guide

2025-11-12 15:34:45 +00:00
parent 1c765f2e51
commit e642752264
1 changed files with 64 additions and 64 deletions
--- a/Contributing-Guide.md
+++ b/Contributing-Guide.md
@@ -2,7 +2,7 @@

 We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help makes this project better.

-### Getting Started
+## Getting Started

 1. **Fork the repository** on Gitea
 2. **Clone your fork:**
@@ -16,9 +16,9 @@ We welcome contributions! Whether you're fixing bugs, adding features, improving
   git checkout -b feature/your-feature-name
   ```

-### Contribution Types
+## Contribution Types

-#### 🐛 Bug Reports
+### 🐛 Bug Reports

 When reporting bugs, please include:
 - **Description**: Clear description of the issue
@@ -61,7 +61,7 @@ Error message appears: "Failed to start server"
 Only happens with servers that have multiple allocations
 ```

-#### ✨ Feature Requests
+### ✨ Feature Requests

 When requesting features:
 - **Use Case**: Explain why this feature is needed
@@ -91,7 +91,7 @@ Add `/backup` command that:
 Many users request this in Discord support channel
 ```

-#### 🔧 Pull Requests
+### 🔧 Pull Requests

 **Before submitting:**
 1. ✅ Tests pass locally (`make test`)
@@ -145,9 +145,9 @@ Relates to #456
 [Any additional information]
 ```

-### Development Guidelines
+## Development Guidelines

-#### Code Style
+### Code Style

 **Commit Messages:**

@@ -207,7 +207,7 @@ chore(deps): update discord.py to 2.3.2
 Security update to address CVE-2024-XXXXX
 ```

-#### Testing Requirements
+### Testing Requirements

 **For Bug Fixes:**
 1. Write failing test that reproduces bug
@@ -249,7 +249,7 @@ class TestNewFeature:
        assert result is not None
 ```

-#### Code Review Process
+### Code Review Process

 **What Reviewers Look For:**

@@ -305,7 +305,7 @@ git push origin feature-branch
 # Once approved, maintainer will merge
 ```

-#### Merging Strategy
+### Merging Strategy

 **We use the following merge strategies:**

@@ -333,7 +333,7 @@ git branch -d feature-branch
 git push origin --delete feature-branch  # Delete remote branch
 ```

-### Documentation Standards
+## Documentation Standards

 **When to Update Documentation:**

@@ -445,7 +445,7 @@ User: [Selects "Minecraft Production"]
 Bot: [Posts status embed in channel]
 ```

-### Dependency Management
+## Dependency Management

 **Adding New Dependencies:**

@@ -518,11 +518,11 @@ requests==2.31.0
 requests==2.31.0 --hash=sha256:abc123...
 ```

-### Performance Considerations
+## Performance Considerations

 **When contributing, consider:**

-#### 1. **API Rate Limits**
+### 1. **API Rate Limits**

 **Problem:** Discord and Pterodactyl APIs have rate limits

@@ -544,7 +544,7 @@ for server in servers:
    await update_embed(server)  # May hit rate limits
 ```

-#### 2. **Memory Usage**
+### 2. **Memory Usage**

 **Problem:** Bot runs 24/7, memory leaks accumulate

@@ -564,7 +564,7 @@ async def cleanup():
 all_data = [expensive_operation(x) for x in huge_list]
 ```

-#### 3. **Blocking Operations**
+### 3. **Blocking Operations**

 **Problem:** Blocking operations freeze the entire bot

@@ -586,7 +586,7 @@ import requests
 response = requests.get(url)  # Blocks entire event loop!
 ```

-#### 4. **Database Queries** (if implemented)
+### 4. **Database Queries** (if implemented)

 **Solutions:**
 ```python
@@ -596,17 +596,17 @@ response = requests.get(url)  # Blocks entire event loop!
 # ❌ Bad - N+1 query problem
 ```

-### Security Considerations
+## Security Considerations

 **Security Checklist for Contributors:**

-#### Authentication & Authorization
+### Authentication & Authorization
 - [ ] All Discord interactions check guild ID
 - [ ] Role requirements enforced for sensitive actions
 - [ ] API keys never logged or displayed
 - [ ] User input validated before use

-#### Input Validation
+### Input Validation
 ```python
 # ✅ Good - Validate user input
 def validate_server_id(server_id: str) -> bool:
@@ -623,7 +623,7 @@ server_id = interaction.data['server_id']
 await api.get_server(server_id)  # No validation!
 ```

-#### Secrets Management
+### Secrets Management
 ```python
 # ✅ Good - From config file
 token = config.get('Discord', 'Token')
@@ -635,7 +635,7 @@ token = os.getenv('DISCORD_TOKEN')
 token = "MTIzNDU2Nzg5.ABCDEF.ghijklmnop"
 ```

-#### Error Handling
+### Error Handling
 ```python
 # ✅ Good - Generic error messages
 try:
@@ -655,7 +655,7 @@ except Exception as e:
    )
 ```

-#### Logging Security
+### Logging Security
 ```python
 # ✅ Good - Sanitize sensitive data
 logger.info(f"User {user.id} executed command")
@@ -666,11 +666,11 @@ logger.debug(f"Using API key: {api_key}")
 logger.info(f"Server details: {server_data}")  # May contain tokens
 ```

-### Troubleshooting Contributions
+## Troubleshooting Contributions

 **Common Issues and Solutions:**

-#### Import Errors
+### Import Errors
 ```bash
 # Problem: ModuleNotFoundError
 # Solution: Install dependencies
@@ -681,7 +681,7 @@ pip install -r requirements.txt -r requirements-test.txt
 export PYTHONPATH="${PYTHONPATH}:$(pwd)"
 ```

-#### Test Failures
+### Test Failures
 ```bash
 # Problem: Tests fail locally
 # Solution 1: Check Python version
@@ -698,7 +698,7 @@ pytest --cache-clear
 pytest test_pterodisbot.py::TestClass::test_method -vv --tb=long
 ```

-#### Linting Failures
+### Linting Failures
 ```bash
 # Problem: Flake8 errors
 # Solution: Auto-fix with black and isort
@@ -714,7 +714,7 @@ black --line-length=120 file.py
 isort --profile black file.py
 ```

-#### Git Issues
+### Git Issues
 ```bash
 # Problem: Merge conflicts
 # Solution: Rebase and resolve
@@ -735,7 +735,7 @@ git reset --soft HEAD~1  # Keep changes
 git reset --hard HEAD~1  # Discard changes
 ```

-#### Docker Issues
+### Docker Issues
 ```bash
 # Problem: Docker build fails
 # Solution: Clear cache and rebuild
@@ -750,11 +750,11 @@ docker logs pterodisbot
 docker run -v $(pwd)/config.ini:/app/config.ini:ro pterodisbot
 ```

-### Testing Your Contribution
+## Testing Your Contribution

 **Before submitting PR, ensure:**

-#### 1. **Unit Tests Pass**
+### 1. **Unit Tests Pass**
 ```bash
 # Run all unit tests
 make test-unit
@@ -767,7 +767,7 @@ make test-coverage
 # Ensure your new code has >80% coverage
 ```

-#### 2. **Integration Tests Pass**
+### 2. **Integration Tests Pass**
 ```bash
 # Run integration tests
 make test-integration
@@ -776,7 +776,7 @@ make test-integration
 pytest test_pterodisbot.py::TestIntegration::test_your_workflow -v
 ```

-#### 3. **Code Quality Passes**
+### 3. **Code Quality Passes**
 ```bash
 # Run all linters
 make lint
@@ -790,7 +790,7 @@ pylint your_file.py
 black --check your_file.py
 ```

-#### 4. **Security Scans Pass**
+### 4. **Security Scans Pass**
 ```bash
 # Run all security checks
 make security
@@ -801,7 +801,7 @@ safety check
 pip-audit
 ```

-#### 5. **Manual Testing**
+### 5. **Manual Testing**
 ```bash
 # Create test config if needed
 cp config.ini.example config.ini
@@ -818,7 +818,7 @@ python pterodisbot.py
 # - Check logs for errors
 ```

-#### 6. **Documentation Updated**
+### 6. **Documentation Updated**
 ```bash
 # Check if documentation needs updates
 # - README.md for user-facing changes
@@ -827,11 +827,11 @@ python pterodisbot.py
 # - Comments for complex logic
 ```

-### Benchmarking and Profiling
+## Benchmarking and Profiling

 **When optimizing performance:**

-#### CPU Profiling
+### CPU Profiling
 ```bash
 # Profile the bot
 python -m cProfile -o profile.stats pterodisbot.py
@@ -846,7 +846,7 @@ pip install snakeviz
 snakeviz profile.stats
 ```

-#### Memory Profiling
+### Memory Profiling
 ```bash
 # Install memory profiler
 pip install memory_profiler
@@ -862,7 +862,7 @@ def my_function():
 python -m memory_profiler pterodisbot.py
 ```

-#### Async Profiling
+### Async Profiling
 ```bash
 # Install yappi
 pip install yappi
@@ -875,7 +875,7 @@ yappi.stop()
 yappi.get_func_stats().print_all()
 ```

-#### Performance Targets
+### Performance Targets

 | Metric | Target | Measurement |
 |--------|--------|-------------|
@@ -886,9 +886,9 @@ yappi.get_func_stats().print_all()
 | Memory usage (average) | <200 MB | Docker stats |
 | API calls per minute | <100 | Log analysis |

-### Advanced Contribution Topics
+## Advanced Contribution Topics

-#### Adding New Bot Commands
+### Adding New Bot Commands

 **Complete sample workflow:**

@@ -982,7 +982,7 @@ yappi.get_func_stats().print_all()

 6. **Test manually and submit PR**

-#### Adding New Metrics
+### Adding New Metrics

 **Complete sample workflow for adding disk I/O metrics:**

@@ -1042,7 +1042,7 @@ yappi.get_func_stats().print_all()

 4. **Update documentation and submit PR**

-#### Extending the API Client
+### Extending the API Client

 **Sample adding support for file management:**

@@ -1083,11 +1083,11 @@ yappi.get_func_stats().print_all()

 3. **Document new API methods and submit PR**

-### Release Management
+## Release Management

 **For maintainers preparing releases:**

-#### Pre-Release Checklist
+### Pre-Release Checklist

 - [ ] All tests passing on main branch
 - [ ] No open critical bugs
@@ -1096,7 +1096,7 @@ yappi.get_func_stats().print_all()
 - [ ] Version bumped in code
 - [ ] Release notes drafted

-#### Release Process
+### Release Process

 1. **Update version:**
   ```python
@@ -1178,7 +1178,7 @@ yappi.get_func_stats().print_all()
   - Post in relevant channels
   - Update external documentation if needed

-#### Hotfix Process
+### Hotfix Process

 **For critical bugs in production:**

@@ -1224,11 +1224,11 @@ yappi.get_func_stats().print_all()

 7. **CI/CD handles deployment automatically**

-###
+##

-### Release Process
+## Release Process

-#### Version Numbering
+### Version Numbering

 We follow [Semantic Versioning](https://semver.org/):

@@ -1245,7 +1245,7 @@ PATCH: Bug fixes (backwards compatible)
 - `v1.2.3` → `v1.3.0`: New feature
 - `v1.2.3` → `v2.0.0`: Breaking change

-#### Creating a Release
+### Creating a Release

 1. **Update version in code:**
   ```python
@@ -1286,9 +1286,9 @@ PATCH: Bug fixes (backwards compatible)
   - Tags: `v1.3.0`, `v1.3`, `v1`, `latest`
   - Pushes to registry

-### Community Guidelines
+## Community Guidelines

-#### Code of Conduct
+### Code of Conduct

 We are committed to providing a welcoming and inclusive environment. All contributors must:

@@ -1300,14 +1300,14 @@ We are committed to providing a welcoming and inclusive environment. All contrib
 - ❌ Make personal attacks
 - ❌ Publish others' private information

-#### Communication Channels
+### Communication Channels

 - **Issues**: Bug reports and feature requests
 - **Pull Requests**: Code contributions and discussions
 - **Discussions**: General questions and ideas
 - **Discord** (if applicable): Real-time community chat

-#### Response Times
+### Response Times

 **Maintainers aim to:**
 - Acknowledge issues within 48 hours
@@ -1319,7 +1319,7 @@ We are committed to providing a welcoming and inclusive environment. All contrib
 - Update PRs to address feedback
 - Close PRs if no longer pursuing

-### Recognition
+## Recognition

 **Contributors are credited in:**
 - CONTRIBUTORS.md file
@@ -1331,7 +1331,7 @@ We are committed to providing a welcoming and inclusive environment. All contrib
 - Be invited to maintain specific areas
 - Help guide project direction

-### Getting Help
+## Getting Help

 **Questions about contributing?**

@@ -1354,7 +1354,7 @@ We are committed to providing a welcoming and inclusive environment. All contrib
   - Clarification on code behavior
   - Help with development setup

-### First-Time Contributors
+## First-Time Contributors

 **Looking for your first contribution?**

@@ -1370,7 +1370,7 @@ Issues labeled with `good-first-issue` are great starting points:
 - Enhance logging
 - Update dependencies

-### Advanced Contributions
+## Advanced Contributions

 **For experienced contributors:**

@@ -1380,7 +1380,7 @@ Issues labeled with `help-wanted` need expertise:
 - Complex feature implementation
 - Security enhancements

-### License
+## License

 By contributing, you agree that your contributions will be licensed under the [GPL-3.0 License](https://git.serendipity.systems/k.eaven/pterodactyl-discord-bot/src/branch/main/LICENSE).

@@ -1448,7 +1448,7 @@ make update               # Update all dependencies
 make freeze               # Generate requirements-frozen.txt
 ```

-### Git Workflow
+## Git Workflow

 ```bash
 # Start new feature
@@ -1471,7 +1471,7 @@ git pull origin main
 git branch -d feature/feature-name
 ```

-### Common Tasks
+## Common Tasks

 **Add new slash command:**
 1. Add command in `pterodisbot.py` with `@bot.tree.command()`