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

December 6, 2025 · View on GitHub

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

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

Содержание

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

Этот проект использует uv для управления зависимостями и предоставляет Makefile для общих задач разработки:

Быстрая настройка

# Одна команда для настройки всего, включая хуки Lefthook
make dev

Эта команда выполнит:

  • Установит зависимости разработки
  • Установит git хуки
  • Запустит хуки Lefthook по всем файлам для исправления существующих проблем

Альтернативная настройка (если предпочитаете шаг за шагом)

# Создать виртуальное окружение и установить зависимости
make setup

# Установить зависимости разработки
make dev

# Установить хуки Lefthook
brew install lefthook  # или смотрите docs ниже для альтернатив
lefthook install
lefthook run pre-commit --all

Доступные команды

  • make setup - Создать виртуальное окружение и установить все зависимости
  • make dev - Полная настройка разработки - включает хуки Lefthook
  • make test - Запустить стандартные тесты (исключает интеграционные тесты)
  • make test-integration - Запустить только интеграционные тесты (требует API-ключи)
  • make test-all - Запустить все тесты
  • make test-cov - Запустить тесты с отчётом о покрытии
  • make lint - Проверить качество кода (ruff, prettier, markdownlint)
  • make format - Автоматически исправить проблемы форматирования кода

Увеличение версии

Важно: PR должны включать увеличение версии в src/gac/__version__.py, когда они содержат изменения, которые должны быть выпущены.

Как увеличить версию

  1. Отредактируйте src/gac/__version__.py и увеличьте номер версии
  2. Следуйте Семантическому версионированию:
    • Patch (1.6.X): Исправления ошибок, небольшие улучшения
    • Minor (1.X.0): Новые функции, обратно совместимые изменения (например, добавление нового поставщика)
    • Major (X.0.0): Обратно несовместимые изменения

Процесс выпуска

Выпуски запускаются отправкой версионных тегов:

  1. Слейте PR(ы) с увеличением версии в main
  2. Создайте тег: git tag v1.6.1
  3. Отправьте тег: git push origin v1.6.1
  4. GitHub Actions автоматически публикует в PyPI

Пример:

# src/gac/__version__.py
__version__ = "1.6.1"  # Увеличено с 1.6.0

Использование bump-my-version (необязательно)

Если у вас установлен bump-my-version, вы можете использовать его локально:

# Для исправлений ошибок:
bump-my-version bump patch

# Для новых функций:
bump-my-version bump minor

# Для обратно несовместимых изменений:
bump-my-version bump major

Стандарты кодирования

  • Цель: Python 3.10+ (3.10, 3.11, 3.12, 3.13, 3.14)
  • Используйте подсказки типов для всех параметров функций и возвращаемых значений
  • Держите код чистым, компактным и читаемым
  • Избегайте ненужной сложности
  • Используйте логирование вместо print-выражений
  • Форматирование обрабатывается ruff (проверка, форматирование и сортировка импортов в одном инструменте; максимальная длина строки: 120)
  • Пишите минимальные, эффективные тесты с pytest

Git хуки (Lefthook)

Этот проект использует Lefthook для поддержания проверок качества кода быстрыми и последовательными. Настроенные хуки зеркалируют нашу предыдущую настройку pre-commit:

  • ruff - Проверка и форматирование Python (заменяет black, isort и flake8)
  • markdownlint-cli2 - Проверка Markdown
  • prettier - Форматирование файлов (markdown, yaml, json)
  • check-upstream - Пользовательский хук для проверки изменений upstream

Настройка

Рекомендуемый подход:

make dev

Ручная настройка (если предпочитаете шаг за шагом):

  1. Установите Lefthook (выберите опцию, соответствующую вашей настройке):

    brew install lefthook          # macOS (Homebrew)
# или
cargo install lefthook         # Rust toolchain
# или
asdf plugin add lefthook && asdf install lefthook latest

  2. Установите git хуки:

    lefthook install

  3. (Необязательно) Запустите по всем файлам:

    lefthook run pre-commit --all

Хуки теперь будут запускаться автоматически при каждом коммите. Если какие-либо проверки не пройдут, вам нужно будет исправить проблемы перед коммитом.

Пропуск Git хуков

Если вам нужно временно пропустить проверки Lefthook, используйте флаг --no-verify:

git commit --no-verify -m "Ваше сообщение коммита"

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

Рекомендации по тестированию

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

Обратите внимание, что каталог scripts/ содержит тестовые скрипты для функциональности, которую трудно протестировать с pytest. Не стесняйтесь добавлять скрипты здесь для тестирования сложных сценариев или интеграционных тестов, которые было бы трудно реализовать с использованием стандартного фреймворка pytest.

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

# Запустить стандартные тесты (исключает интеграционные тесты с реальными вызовами API)
make test

# Запустить только интеграционные тесты поставщиков (требует API-ключи)
make test-integration

# Запустить все тесты включая интеграционные тесты поставщиков
make test-all

# Запустить тесты с покрытием
make test-cov

# Запустить конкретный тестовый файл
uv run -- pytest tests/test_prompt.py

# Запустить конкретный тест
uv run -- pytest tests/test_prompt.py::TestExtractRepositoryContext::test_extract_repository_context_with_docstring

Интеграционные тесты поставщиков

Интеграционные тесты поставщиков делают реальные вызовы API для проверки, что реализации поставщиков работают корректно с фактическими API. Эти тесты отмечены @pytest.mark.integration и пропускаются по умолчанию чтобы:

  • Избегать потребления API-кредитов во время регулярной разработки
  • Предотвратить сбои тестов, когда API-ключи не настроены
  • Держать выполнение тестов быстрым для быстрой итерации

Для запуска интеграционных тестов поставщиков:

  1. Настройте API-ключи для поставщиков, которые вы хотите протестировать:

    export ANTHROPIC_API_KEY="your-key"
export CEREBRAS_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export OPENROUTER_API_KEY="your-key"
export STREAMLAKE_API_KEY="your-key"
export ZAI_API_KEY="your-key"
# LM Studio и Ollama требуют работы локального экземпляра
# API-ключи для LM Studio и Ollama необязательны, если ваше развертывание не требует аутентификации

  2. Запустите тесты поставщиков:

    make test-integration

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

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

Будьте уважительными и конструктивными. Домогательства или оскорбительное поведение не будут терпеться.

Лицензия

Участвуя, вы соглашаетесь, что ваши вклады будут лицензированы под той же лицензией, что и проект.

Где получить помощь

  • Для устранения неполадок смотрите TROUBLESHOOTING.md
  • Для использования и опций CLI смотрите USAGE.md
  • Для деталей лицензии смотрите LICENSE

Спасибо за помощь в улучшении gac!