Руководство по участию

Мы принимаем вклад в Django-GC. Это руководство описывает локальный процесс разработки, тестов и документации.

Если неясно, подходит ли изменение проекту, сначала откройте issue или draft pull request.

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

Настройка окружения

Проект использует uv для Python-зависимостей. Установка — в документации uv.

После клонирования репозитория установите зависимости:

uv sync --group dev

Линтинг

Ruff читает ruff.toml: длина строки 120, список ignore проекта и force-exclude для миграций и Markdown. Не запускайте Ruff без этого файла — дефолты конфликтуют с атрибутами Django admin и примерами в доках.

uv run ruff check --config ruff.toml .
uv run ruff format --check --config ruff.toml .
uv run pyrefly check

Тесты

uv run pytest

Документация

Документация собирается Docusaurus. Сайт двуязычный (английский источник, русские зеркала) и не версионируется. Публичный API помечается бейджами <Since v="x.y.z" />.

cd docs
npm install
npm run docs:dev

Английский — локаль по умолчанию на /, без префикса /en/. Русский — i18n overlay на /ru/. docs:dev поднимает английский на порту 3100, русский на 3101 (под /ru/) и проксирует /ru с английского сервера, чтобы переключатель языка работал в обе стороны. Порты не пересекаются с Django-Chassis (3000/3001), оба сайта можно держать одновременно. Если нужно переключать языки, запускайте docs:dev, а не один docs:dev:ru.

npm run docs:build
npm run docs:serve

Бейджи версий

Любая новая публичная настройка, тип или extra должна быть помечена на обоих языках:

<Since v="1.1.0" />

Изменения поведения или сигнатуры — <Changed v="..." /> и запись в CHANGELOG.md. Версия бейджа — версия пакета, в которой фича впервые вышла.

Соглашения проекта

• Полная типизация — аннотируйте параметры, возврат и переменные. Цель — pyrefly strict.
• Без относительных импортов — только абсолютные (from django_gc.services import get_value).
• Именованные аргументы — передавайте аргументы по имени, где возможно.
• uv run — команды Python как uv run pytest, не голый python.
• Runtime-код читает и пишет через get_value() / set_value(), не через ORM.
• Доменные ключи живут в проектном StrEnum и передаются в эти вызовы.
• Английская и русская документация остаются синхронными.
• Изменения публичного API требуют записи в CHANGELOG.md.