Перейти к содержанию

Контрибьютинг в проект eebook

Добро пожаловать в гайд для контрибьюторов! Здесь описано, как правильно участвовать в разработке проекта, чтобы код был чистым, тестируемым и соответствовал стандартам.

1. Общие правила

  • Все изменения проходят через Pull Request.
  • Перед PR необходимо обновить локальную ветку с main: 
    git checkout feature/your-feature
git fetch origin
git rebase origin/main
    PR должен быть маленьким и логически завершённым. Все публичные методы и классы должны иметь докстринги. Соблюдаем PEP8 / PSR-12 и типизацию. Перед PR выполняем тесты и линтинг: 
    pre-commit run --all-files
pytest --cov=src

2. Ветка и коммиты

  • Каждая новая фича/исправление в своей ветке: 

    feature/<короткое-описание>
bugfix/<короткое-описание>

  • Коммиты в формате Conventional Commits: 

    feat(auth): add JWT authentication
fix(portfolio): correct income calculation
docs: update API docs
refactor(service_layer): simplify calculation logic
    Коммиты атомарные: одна логическая задача = один коммит.

3. Pull Request

  • Название PR — краткое описание фичи или исправления.
  • В описании указываем:
    • Что сделано
    • Ссылки на задачи/тикеты
    • Что проверено вручную/тестами
  • PR должен пройти Code Review хотя бы одного разработчика.
  • После approval — merge через Squash and Merge или Rebase (по договорённости команды).

4. Тестирование изменений

  • Любая бизнес-логика должна быть покрыта unit-тестами.
  • Используем pytest, фикстуры для повторного использования данных.
  • Для работы с внешними сервисами (DB, Vault) используем mocking / fixtures.
  • Проверяем покрытие: минимум 60% для мержей в main.

5. Документация изменений

  • Если добавлена новая публичная функция или класс — пишем докстринги.
  • Если API изменилось — обновляем API-документацию (MkDocs + mkdocstrings).
  • README или другие гайды обновляем при необходимости.

6. Стиль и лучшие практики

  • Clean Architecture / DDD: соблюдаем слои, зависимости внутрь.
  • KISS и DRY: простота и отсутствие дублирования.
  • Минимизируем побочные эффекты: функции и методы должны быть детерминированными.
  • Логика бизнес-сущностей только в domain / service_layer.
  • Работа с внешними системами через адаптеры (adapters) и интерфейсы.

7. Общение и помощь

  • Вопросы по проекту — через тикеты или internal чат.
  • Не стесняемся делать маленькие PR и спрашивать советы.
  • Все участники следят за единообразием кода и архитектуры.

Совет: перед любым PR сначала проверьте, что линтер не ругается, тесты проходят, и все слои архитектуры соблюдены.