mirror of
https://github.com/BEDOLAGA-DEV/remnawave-bedolaga-telegram-bot.git
synced 2026-01-20 03:40:26 +00:00
481 lines
17 KiB
Markdown
481 lines
17 KiB
Markdown
# 🤝 Contributing to Remnawave Bedolaga Bot
|
||
|
||
Спасибо за интерес к развитию проекта! Этот документ содержит правила и рекомендации для контрибьюторов.
|
||
|
||
## 📋 Содержание
|
||
|
||
- [Кодекс поведения](#-кодекс-поведения)
|
||
- [Как помочь проекту](#-как-помочь-проекту)
|
||
- [Настройка среды разработки](#-настройка-среды-разработки)
|
||
- [Стандарты кода](#-стандарты-кода)
|
||
- [Работа с Git](#-работа-с-git)
|
||
- [Тестирование](#-тестирование)
|
||
- [Процесс ревью](#-процесс-ревью)
|
||
- [Документация](#-документация)
|
||
|
||
## 📜 Кодекс поведения
|
||
|
||
### Основные принципы
|
||
|
||
- **Уважение** - относитесь к участникам проекта с уважением
|
||
- **Конструктивность** - предлагайте решения, а не только критику
|
||
- **Открытость** - будьте открыты к обратной связи и новым идеям
|
||
- **Профессионализм** - поддерживайте высокий уровень обсуждений
|
||
|
||
### Недопустимое поведение
|
||
|
||
- Оскорбления и личные атаки
|
||
- Спам и офф-топик сообщения
|
||
- Публикация приватной информации
|
||
- Любые формы дискриминации
|
||
|
||
## 🚀 Как помочь проекту
|
||
|
||
### 🐛 Сообщения о багах
|
||
|
||
Перед созданием issue проверьте:
|
||
- [ ] Аналогичная проблема не была описана ранее
|
||
- [ ] Вы используете актуальную версию бота
|
||
- [ ] Проблема воспроизводится стабильно
|
||
|
||
**Шаблон для багрепорта:**
|
||
|
||
```markdown
|
||
## 🐛 Описание бага
|
||
Краткое описание проблемы
|
||
|
||
## 🔄 Шаги воспроизведения
|
||
1. Перейти к '...'
|
||
2. Нажать на '...'
|
||
3. Увидеть ошибку
|
||
|
||
## ✅ Ожидаемое поведение
|
||
Что должно было произойти
|
||
|
||
## ❌ Фактическое поведение
|
||
Что произошло на самом деле
|
||
|
||
## 🌍 Окружение
|
||
- Версия бота: [например, 1.0.0]
|
||
- Python версия: [например, 3.11.7]
|
||
- ОС: [например, Ubuntu 22.04]
|
||
- Версия Docker: [если используется]
|
||
|
||
## 📋 Логи
|
||
```
|
||
Вставьте соответствующие логи
|
||
```
|
||
|
||
## 📷 Скриншоты
|
||
Если применимо, добавьте скриншоты
|
||
```
|
||
|
||
### 💡 Предложения функций
|
||
|
||
Используйте лейбл `enhancement` и опишите:
|
||
- **Проблему**, которую решает функция
|
||
- **Предлагаемое решение**
|
||
- **Альтернативы**, которые вы рассматривали
|
||
- **Дополнительную информацию** и контекст
|
||
|
||
### 📝 Улучшение документации
|
||
|
||
- Исправление опечаток
|
||
- Дополнение примеров
|
||
- Перевод на другие языки
|
||
- Улучшение структуры
|
||
|
||
## 🛠 Настройка среды разработки
|
||
|
||
### Требования
|
||
|
||
- Python 3.11+
|
||
- Docker и Docker Compose
|
||
- Git
|
||
- PostgreSQL 15+ (опционально для локальной разработки)
|
||
- Redis (опционально для локальной разработки)
|
||
|
||
### Установка
|
||
|
||
1. **Форкните и клонируйте репозиторий:**
|
||
```bash
|
||
git clone https://github.com/Fr1ngg/remnawave-bedolaga-telegram-bot.git
|
||
cd remnawave-bedolaga-telegram-bot
|
||
```
|
||
|
||
2. **Создайте виртуальное окружение:**
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# или
|
||
venv\Scripts\activate # Windows
|
||
```
|
||
|
||
3. **Установите зависимости:**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
pip install -r requirements-dev.txt # если есть dev зависимости
|
||
```
|
||
|
||
4. **Настройте окружение:**
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте .env файл с вашими настройками
|
||
```
|
||
|
||
5. **Запустите через Docker (рекомендуется):**
|
||
```bash
|
||
docker compose up -d postgres redis
|
||
python main.py
|
||
```
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
bedolaga_bot/
|
||
├── app/ # Основной код приложения
|
||
│ ├── handlers/ # Обработчики сообщений
|
||
│ ├── services/ # Бизнес-логика
|
||
│ ├── database/ # Модели и CRUD операции
|
||
│ ├── utils/ # Утилиты
|
||
│ ├── middlewares/ # Middleware
|
||
│ └── external/ # Внешние API
|
||
├── migrations/ # Миграции БД (если нужны)
|
||
├── tests/ # Тесты (создать при необходимости)
|
||
├── docs/ # Документация
|
||
└── requirements.txt # Зависимости
|
||
```
|
||
|
||
## 🎨 Стандарты кода
|
||
|
||
### Python стиль
|
||
|
||
Мы следуем **PEP 8** с некоторыми исключениями:
|
||
|
||
```python
|
||
# ✅ Хорошо
|
||
async def get_user_subscription(user_id: int) -> Optional[Subscription]:
|
||
"""Получает активную подписку пользователя."""
|
||
async with get_session() as session:
|
||
result = await session.execute(
|
||
select(Subscription)
|
||
.where(Subscription.user_id == user_id)
|
||
.where(Subscription.is_active == True)
|
||
)
|
||
return result.scalar_one_or_none()
|
||
|
||
# ❌ Плохо
|
||
async def getUserSub(uid):
|
||
session = get_session()
|
||
sub = session.query(Subscription).filter(Subscription.user_id==uid,Subscription.is_active==True).first()
|
||
return sub
|
||
```
|
||
|
||
### Правила именования
|
||
|
||
- **Функции и переменные**: `snake_case`
|
||
- **Классы**: `PascalCase`
|
||
- **Константы**: `UPPER_CASE`
|
||
- **Приватные методы**: `_leading_underscore`
|
||
|
||
### Типизация
|
||
|
||
Обязательно используйте type hints:
|
||
|
||
```python
|
||
from typing import Optional, List, Dict, Any
|
||
|
||
async def create_subscription(
|
||
user_id: int,
|
||
duration_days: int,
|
||
traffic_limit_gb: Optional[int] = None
|
||
) -> Subscription:
|
||
"""Создает новую подписку."""
|
||
# implementation
|
||
```
|
||
|
||
### Документация кода
|
||
|
||
```python
|
||
async def calculate_subscription_price(
|
||
period_days: int,
|
||
traffic_gb: int,
|
||
devices_count: int,
|
||
servers_count: int
|
||
) -> int:
|
||
"""
|
||
Рассчитывает стоимость подписки.
|
||
|
||
Args:
|
||
period_days: Период подписки в днях
|
||
traffic_gb: Лимит трафика в ГБ (0 = безлимит)
|
||
devices_count: Количество устройств
|
||
servers_count: Количество серверов
|
||
|
||
Returns:
|
||
Стоимость в копейках
|
||
|
||
Raises:
|
||
ValueError: Если переданы некорректные параметры
|
||
"""
|
||
# implementation
|
||
```
|
||
|
||
### Обработка ошибок
|
||
|
||
```python
|
||
# ✅ Хорошо
|
||
try:
|
||
subscription = await subscription_service.create_subscription(user_id, data)
|
||
await message.answer("✅ Подписка создана успешно!")
|
||
except RemnaWaveAPIError as e:
|
||
logger.error(f"RemnaWave API error: {e}")
|
||
await message.answer("❌ Ошибка при создании подписки. Попробуйте позже.")
|
||
except ValidationError as e:
|
||
logger.warning(f"Validation error: {e}")
|
||
await message.answer("❌ Некорректные данные для создания подписки.")
|
||
|
||
# ❌ Плохо
|
||
try:
|
||
subscription = await subscription_service.create_subscription(user_id, data)
|
||
await message.answer("✅ Подписка создана успешно!")
|
||
except:
|
||
await message.answer("Ошибка")
|
||
```
|
||
|
||
### Логирование
|
||
|
||
```python
|
||
import logging
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
# Уровни логирования
|
||
logger.debug("Детальная информация для отладки")
|
||
logger.info("Общая информация о работе")
|
||
logger.warning("Предупреждение о потенциальной проблеме")
|
||
logger.error("Ошибка, которая не прерывает работу")
|
||
logger.critical("Критическая ошибка")
|
||
```
|
||
|
||
## 🔄 Работа с Git
|
||
|
||
### Ветки
|
||
|
||
- `main` - стабильная версия
|
||
- `dev` - разработка новых функций
|
||
|
||
### Коммиты
|
||
|
||
Используйте [Conventional Commits](https://www.conventionalcommits.org/):
|
||
|
||
```bash
|
||
# Типы коммитов
|
||
feat: добавить поддержку CryptoBot платежей
|
||
fix: исправить ошибку с расчетом цены подписки
|
||
docs: обновить документацию по настройке
|
||
style: исправить форматирование кода
|
||
refactor: рефакторинг сервиса платежей
|
||
test: добавить тесты для subscription_service
|
||
chore: обновить зависимости
|
||
|
||
# Примеры
|
||
git commit -m "feat(payments): добавить поддержку YooKassa webhook"
|
||
git commit -m "fix(subscription): исправить расчет стоимости устройств"
|
||
git commit -m "docs(readme): обновить инструкцию по установке"
|
||
```
|
||
|
||
### Pull Request процесс
|
||
|
||
1. **Создайте ветку** от `dev`:
|
||
```bash
|
||
git checkout develop
|
||
git pull origin develop
|
||
git checkout -b feature/new-payment-method
|
||
```
|
||
|
||
2. **Разработайте функцию** с соблюдением стандартов
|
||
|
||
3. **Протестируйте** изменения локально
|
||
|
||
4. **Создайте Pull Request** с описанием:
|
||
|
||
```markdown
|
||
## 📝 Описание
|
||
Краткое описание изменений
|
||
|
||
## 🎯 Мотивация
|
||
Почему эти изменения нужны?
|
||
|
||
## 🔧 Тип изменений
|
||
- [ ] Bug fix (исправление)
|
||
- [ ] New feature (новая функция)
|
||
- [ ] Breaking change (ломающие изменения)
|
||
- [ ] Documentation update (обновление документации)
|
||
|
||
## ✅ Чеклист
|
||
- [ ] Код соответствует стандартам проекта
|
||
- [ ] Добавлены/обновлены тесты
|
||
- [ ] Документация обновлена
|
||
- [ ] Проверена работа в Docker
|
||
- [ ] Проверена совместимость с существующим API
|
||
|
||
## 🧪 Тестирование
|
||
Как тестировались изменения:
|
||
- [ ] Локальное тестирование
|
||
- [ ] Тестирование с реальным Remnawave API
|
||
- [ ] Тестирование платежных систем
|
||
```
|
||
|
||
## 🧪 Тестирование
|
||
|
||
### Локальное тестирование
|
||
|
||
```bash
|
||
# Запуск с тестовой базой
|
||
export DATABASE_URL="sqlite:///test.db"
|
||
export BOT_TOKEN="test_token"
|
||
python main.py
|
||
```
|
||
|
||
### Тестирование компонентов
|
||
|
||
```python
|
||
# tests/test_subscription_service.py
|
||
import pytest
|
||
from app.services.subscription_service import SubscriptionService
|
||
|
||
@pytest.mark.asyncio
|
||
async def test_calculate_price():
|
||
price = await SubscriptionService.calculate_subscription_price(
|
||
period_days=30,
|
||
traffic_gb=100,
|
||
devices_count=3,
|
||
servers_count=1
|
||
)
|
||
assert price > 0
|
||
assert isinstance(price, int)
|
||
```
|
||
|
||
### Integration тесты
|
||
|
||
Тестируйте интеграцию с:
|
||
- Remnawave API (с тестовыми данными)
|
||
- Базой данных
|
||
- Платежными системами (sandbox режим)
|
||
|
||
## 👀 Процесс ревью
|
||
|
||
### Требования для ревьюера
|
||
|
||
- Проверить соответствие стандартам кода
|
||
- Убедиться в работоспособности
|
||
- Проверить безопасность (особенно для платежных функций)
|
||
- Оценить производительность
|
||
- Проверить совместимость с существующим API
|
||
|
||
### Требования для автора
|
||
|
||
- Ответить на все комментарии
|
||
- Исправить замечания
|
||
- Обновить документацию при необходимости
|
||
- Убедиться в прохождении всех проверок
|
||
|
||
## 📚 Документация
|
||
|
||
### Обновление документации
|
||
|
||
При добавлении новых функций обновляйте:
|
||
|
||
- `README.md` - если изменился API или конфигурация
|
||
- Комментарии в коде
|
||
- Примеры использования
|
||
- Changelog (если есть)
|
||
|
||
### Стиль документации
|
||
|
||
- Используйте ясный и понятный язык
|
||
- Добавляйте примеры кода
|
||
- Указывайте возможные ошибки и их решения
|
||
- Используйте эмодзи для улучшения читаемости
|
||
|
||
## 🏷 Лейблы Issues и PR
|
||
|
||
### Приоритет
|
||
- `priority:high` - высокий приоритет
|
||
- `priority:medium` - средний приоритет
|
||
- `priority:low` - низкий приоритет
|
||
|
||
### Тип
|
||
- `bug` - ошибка
|
||
- `enhancement` - улучшение
|
||
- `feature` - новая функция
|
||
- `documentation` - документация
|
||
- `question` - вопрос
|
||
|
||
### Область
|
||
- `payments` - платежные системы
|
||
- `api` - Remnawave API
|
||
- `database` - база данных
|
||
- `ui/ux` - интерфейс пользователя
|
||
- `admin` - админ панель
|
||
|
||
## 🔐 Безопасность
|
||
|
||
### Сообщения о уязвимостях
|
||
|
||
Для сообщений о критических уязвимостях безопасности:
|
||
- Свяжитесь с [@fringg](https://t.me/fringg) напрямую
|
||
- Не создавайте публичные issues для уязвимостей
|
||
- Дайте время на исправление перед публичным раскрытием
|
||
|
||
### Рекомендации по безопасности
|
||
|
||
- Никогда не коммитьте API ключи и пароли
|
||
- Используйте переменные окружения для чувствительных данных
|
||
- Валидируйте все пользовательские данные
|
||
- Используйте HTTPS для всех внешних запросов
|
||
|
||
## 📞 Получение помощи
|
||
|
||
### Каналы связи
|
||
|
||
- **💬 Telegram Group:** [Bedolaga Chat](https://t.me/+wTdMtSWq8YdmZmVi) - общие вопросы
|
||
- **🐛 GitHub Issues:** Технические вопросы и баги
|
||
- **📧 Прямой контакт:** [@fringg](https://t.me/fringg) - только критические вопросы
|
||
|
||
### Часто задаваемые вопросы
|
||
|
||
**Q: Как настроить локальную разработку без Docker?**
|
||
A: Установите PostgreSQL и Redis локально, обновите DATABASE_URL и REDIS_URL в .env
|
||
|
||
**Q: Можно ли использовать SQLite для разработки?**
|
||
A: Да, установите DATABASE_MODE=sqlite в .env
|
||
|
||
**Q: Как тестировать платежные системы?**
|
||
A: Используйте тестовые/sandbox режимы платежных систем
|
||
|
||
**Q: Что делать, если тесты не проходят?**
|
||
A: Проверьте конфигурацию .env и убедитесь, что все сервисы запущены
|
||
|
||
## 📋 Чеклист для контрибьюторов
|
||
|
||
Перед отправкой PR убедитесь:
|
||
|
||
- [ ] ✅ Код соответствует стандартам проекта
|
||
- [ ] 📝 Добавлены комментарии и docstrings
|
||
- [ ] 🧪 Функциональность протестирована
|
||
- [ ] 📚 Документация обновлена
|
||
- [ ] 🔒 Нет чувствительных данных в коде
|
||
- [ ] 🐳 Изменения работают в Docker
|
||
- [ ] 📋 PR создан с подробным описанием
|
||
- [ ] 🏷 Проставлены соответствующие лейблы
|
||
|
||
## 🎉 Благодарности
|
||
|
||
Спасибо всем, кто вносит вклад в развитие проекта! Ваша помощь делает Bedolaga Bot лучше для всего сообщества.
|
||
|
||
---
|
||
|
||
**Made with ❤️ by community**
|