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

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

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

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

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

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

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

uv sync --group dev

Линтинг

uv run ruff check .
uv run pyrefly check
uv run pytest tests/test_source_conventions.py -q

Ruff проверяет и пакет, и набор тестов. Ограничивайте исключения правил самым узким подходящим файлом или путём и документируйте, какой контракт фреймворка их требует. Настроенные кириллические confusables поддерживают русские UI-строки и docstrings без отключения проверок RUF001–RUF003.

B009 и B010 отключены, поскольку интеграции Django обоснованно читают и добавляют динамические атрибуты объектов фреймворка через getattr() и setattr(); требование прямого доступа вынуждало бы создавать искусственные протоколы только ради проверки типов.

Pyrefly проверяет django_chassis со strict preset и минимальной поддерживаемой версией Python. Отключены стилистические правила missing-override-decorator и implicit-any-lambda. Правило implicit-any-attribute отключено, чтобы сохранять присваивания в Django-классах Meta моделей без аннотаций; несовместимые сигнатуры методов остаются ошибками через bad-override.

Тесты

uv run pytest

Тестовый pipeline GitHub Actions запускает linting и строгую проверку типов на Python 3.13, затем полный набор тестов на Python 3.13 и 3.14. Задачи матрицы не останавливаются после первого сбоя, поэтому каждая поддерживаемая версия Python выдаёт свой результат.

Работа с документацией

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

cd docs
npm install
npm run docs:dev

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

npm run docs:build
npm run docs:serve

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

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

<Since v="1.1.0" />

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

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

• Полная типизация — аннотируйте каждый параметр функции, возвращаемое значение и переменную, кроме атрибутов внутри Django-классов Meta моделей. Проект целится в строгий режим pyrefly. Runtime-классы Django, которые не поддерживают параметризацию, например Field и ModelAdmin, остаются непараметризованными в аннотациях.
• Без относительных импортов — всегда абсолютные (from django_chassis.mixins import ChassisAdminMixin).
• Именованные аргументы — передавайте аргументы по ключу, где возможно.
• Сигнатуры функций — если сигнатура не помещается в одну строку, переносите каждый параметр на отдельную строку.
• Завершающие запятые — не оставляйте необязательную запятую после последнего параметра, аргумента или элемента коллекции. Ruff formatter отключён, потому что он требует запятые в многострочных коллекциях. Поддерживаемые случаи проверяет COM819, а многострочный синтаксис — source-conventions checker.
• Форматирование — не запускайте ruff format; для автоматических проверок стиля используйте uv run ruff check ..
• Миграции — никогда не редактируйте и не переписывайте механически файлы в Django-каталогах migrations. Они глобально исключены из pre-commit, Ruff, Pyrefly и source-conventions проверок.
• Импорты — I001 отключено, поскольку isort требует завершающие запятые в многострочных блоках импортов. Проверка абсолютных импортов остаётся включена.
• Lambda-выражения — сохраняйте компактные lambda; не заменяйте их именованными функциями или прямыми ссылками только ради линтера или типизации.
• Директивы noqa — сохраняйте существующие комментарии # noqa; не удаляйте и не переписывайте добавленные сопровождающим исключения без прямого указания.
• Менеджеры моделей — объявляйте Django-классы Manager и QuerySet в django_chassis.models.managers, а не в модулях моделей.
• Метаданные Django-моделей — используйте обычные присваивания внутри классов Meta моделей; не добавляйте аннотации типов, в том числе к default_permissions = (). Это правило контролирует source-conventions checker; правило Pyrefly implicit-any-attribute отключено, чтобы оно не требовало аннотацию для пустого кортежа.
• Имена классов — не создавайте классы с _ в начале имени без явного разрешения сопровождающего; используйте содержательное публичное имя.
• uv run — Python-команды как uv run pytest, не голый python.
• options остаётся options — не переименовывайте атрибут ModelAdmin.
• Порядок миксинов — ChassisAdminMixin / ChassisAdminSiteMixin перед классом Django.
• Порядок INSTALLED_APPS — 'django_chassis' перед 'django.contrib.admin'.
• Английская и русская документация остаются синхронными.
• Изменения публичного API требуют записи в CHANGELOG.md.