Участие в разработке CulicidaeLab

Прежде всего, благодарим вас за то, что вы решили внести свой вклад в CulicidaeLab! Мы очень рады видеть вас здесь и ценим ваш интерес к улучшению этого проекта. Каждый вклад, от исправления небольшой опечатки до добавления крупной новой функции, очень важен.

Этот документ содержит руководство по участию в проекте. Пожалуйста, внимательно прочтите его, чтобы обеспечить гладкий и эффективный процесс совместной работы.

Кодекс поведения

Этот проект и все его участники руководствуются Кодексом поведения CulicidaeLab. Участвуя в проекте, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о неприемлемом поведении по адресу iloncka.ds@gmail.com.

Как я могу внести вклад?

Существует множество способов внести свой вклад, и мы приветствуем каждый из них:

• Сообщение об ошибках: Если вы нашли ошибку, пожалуйста, откройте «issue» (проблему) и предоставьте подробную информацию, включая шаги для ее воспроизведения.
• Предложение улучшений: У вас есть идея для новой функции или улучшения существующей? Откройте «issue», чтобы начать обсуждение.
• Написание документации: Помогите нам улучшить нашу документацию, исправляя опечатки, проясняя непонятные разделы или добавляя новые примеры.
• Отправка пулл-реквестов: Если вы готовы внести свой вклад в код, это лучший способ.

Сообщение об ошибках

Перед созданием отчета об ошибке, пожалуйста, проверьте существующие «issues», чтобы убедиться, что о проблеме еще не сообщалось. Если нет, пожалуйста, откройте новую «issue» и включите следующее:

• Четкий и описательный заголовок.
• Версия culicidaelab, которую вы используете.
• Ваша операционная система и версия Python.
• Пошаговое описание того, как воспроизвести ошибку.
• Фрагмент кода, демонстрирующий проблему.
• Полная трассировка стека любых сообщений об ошибках.

Предложение улучшений

Мы будем рады услышать ваши идеи по улучшению CulicidaeLab. Чтобы предложить улучшение, пожалуйста, откройте «issue» и предоставьте:

• Четкий и описательный заголовок.
• Подробное объяснение предлагаемого улучшения и почему оно будет полезным.
• (Необязательно) Примерный набросок того, как функция может быть реализована или использована в коде.

Настройка среды разработки

Готовы написать код? Вот как настроить вашу среду разработки.

1. Сделайте форк репозитория Начните с создания форка основного репозитория на GitHub.

2. Клонируйте ваш форк Клонируйте ваш форк-репозиторий на свой локальный компьютер:

   git clone https://github.com/ВАШ_ЛОГИН/culicidaelab.git
   cd culicidaelab
   

3. Создайте виртуальное окружение Настоятельно рекомендуется работать в виртуальном окружении. Вы можете использовать uv или встроенный в Python модуль venv.

   # Используя uv (рекомендуется)
   uv venv
   
   # Или используя venv
   python -m venv .venv
   

   Активируйте окружение:

   # На macOS/Linux
   source .venv/bin/activate
   
   # На Windows
   .venv\Scripts\activate
   

4. Установите зависимости Установите проект в редактируемом режиме (-e) вместе со всеми зависимостями для разработки ([dev]).

   uv pip install -e ".[dev]"
   

   Эта команда устанавливает все необходимое для разработки, включая инструменты для тестирования, линтеры и генераторы документации.

5. Установите хуки pre-commit Мы используем pre-commit для автоматического запуска линтеров и форматеров перед каждым коммитом. Это обеспечивает качество и согласованность кода во всем проекте.

   pre-commit install
   

   Это разовая настройка для каждого клона. Теперь при каждом выполнении git commit будут запускаться хуки, определенные в .pre-commit-config.yaml.

Наш процесс разработки

Мы используем набор инструментов для поддержания качества кода. Ваша настройка pre-commit обрабатывает все это автоматически, но полезно знать, что происходит «под капотом».

• Форматирование: black и ruff-format используются для детерминированного и согласованного форматирования кода.
• Линтинг: ruff и flake8 выявляют распространенные ошибки программирования и проблемы со стилем.
• Проверка типов: mypy выполняет статическую проверку типов для поиска ошибок, связанных с типами, до времени выполнения.
• Безопасность: bandit сканирует код на наличие распространенных уязвимостей безопасности.
• Модернизация: pyupgrade автоматически обновляет синтаксис до более новых версий Python.

Запуск тестов

Чтобы убедиться, что ваши изменения не привели к регрессиям, пожалуйста, запустите полный набор тестов с помощью pytest.

pytest

Все тесты должны проходить успешно перед отправкой пулл-реквеста.

Написание документации

Хорошая документация так же важна, как и хороший код. Если вы добавляете или изменяете функцию, пожалуйста, обновите документацию в каталоге docs/ соответствующим образом.

Вы можете предварительно просмотреть свои изменения локально, выполнив:

mkdocs serve

Это запустит локальный сервер, и вы сможете просмотреть сайт документации в своем браузере по адресу http://127.0.0.1:8000.

Отправка пулл-реквеста

Когда вы будете готовы отправить свои изменения, пожалуйста, следуйте этим шагам:

1. Создайте новую ветку Создайте описательную ветку для ваших изменений от ветки main.

   git checkout -b feature/your-awesome-feature
   

2. Внесите свои изменения Напишите свой код, добавьте или обновите тесты и напишите документацию.

3. Закоммитьте свою работу Закоммитьте свои изменения с четким и кратким сообщением. Когда вы делаете коммит, запустятся хуки pre-commit. Если они не сработают, исправьте указанные проблемы и закоммитьте снова.

   git add .
   git commit -m "feat: Добавлена новая замечательная функция"
   

4. Отправьте изменения в ваш форк Отправьте вашу ветку в ваш форк-репозиторий на GitHub.

   git push origin feature/your-awesome-feature
   

5. Откройте пулл-реквест Перейдите в репозиторий CulicidaeLab на GitHub и откройте пулл-реквест.

   • Укажите четкий заголовок и подробное описание ваших изменений.
   • Если ваш PR решает существующую «issue», сошлитесь на нее, включив Closes #123 в описание.

6. Ревью кода Как только ваш PR будет отправлен, мейнтейнер его рассмотрит. Мы можем предложить некоторые изменения или улучшения. Мы сделаем все возможное, чтобы предоставить своевременную и конструктивную обратную связь.

Еще раз спасибо за ваш интерес к участию в проекте! Мы с нетерпением ждем ваших предложений.