Skip to content

Latest commit

 

History

History
179 lines (133 loc) · 8.57 KB

CONTRIBUTING.ru.md

File metadata and controls

179 lines (133 loc) · 8.57 KB

Вклад в ktav (Python)

Languages: English · Русский · 简体中文

Основные правила

1. Каждый багфикс сопровождается регрессионным тестом

Когда вы нашли баг, до того, как его исправлять, напишите воспроизводящий тест — он должен падать на main и проходить после фикса. И тест, и фикс — в одном PR.

Тесты лежат в tests/:

Файл Область
test_loads.py Поведение парсера.
test_dumps.py Поведение сериализатора.
test_roundtrip.py loads(dumps(x)) == x.
test_errors.py Таксономия и распространение исключений.
test_load_dump.py Обёртки под файл-подобные объекты.
test_module.py Экспорты модуля, строки версий.
test_conformance.py Кросс-языковое соответствие спецификации.

2. Не изобретайте формат заново в биндингах

Эти Python-биндинги — намеренно тонкая обёртка. Поведение парсера и формата принадлежит Rust-крейту (ktav-lang/rust) — изменение там сразу обновляет все языковые биндинги. В этом репозитории живёт только Python-специфичная эргономика (обёртки под файл-подобные объекты, типы исключений, заглушки типов).

Если ваше изменение требует правки формата, начните с обсуждения в ktav-lang/spec.

3. Изменения публичного API указывают совместимость

Если вы трогаете что-то экспортируемое из ktav или ktav._core, в описании PR укажите, является ли это:

  • semver-совместимым (добавления, ослабленные типы, правки документации); или
  • semver-ломающим (переименование / удаление, изменение сигнатур, ужесточение типов) — в этом случае бамп версии попадёт в следующий MINOR, пока мы до 1.0.

Обновите CHANGELOG-юниты под root-docs/CHANGELOG/ (все три блока >>>>> lang=) в том же PR и перегенерируйте вывод.

4. Одна концепция — один коммит

Коммиты атомарны: багфикс и его тест вместе, фича и её тесты вместе, переименование отдельным коммитом, рефакторинг отдельным. git log --oneline должен читаться как журнал изменений. Не префиксуйте сообщения feat: / fix: — никаких conventional commits здесь.

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

Нужно:

  • Python 3.9+ (любая версия, под которую тестируете).
  • Rust-тулчейн через rustup. MSRV: 1.70.
  • maturin и тестовый инструментарий:
pip install -e ".[dev]"

Раскладка во время разработки — эти биндинги разрешают Rust-крейт ktav через зависимость path = "../rust" в Cargo.toml. Клонируйте соседний репозиторий рядом с этим:

ktav-lang/
├── python/   ← this repo
├── rust/     ← sibling Rust crate
└── spec/     ← conformance fixtures (optional but recommended)

Когда ktav будет опубликован на crates.io, path-зависимость уйдёт, и останется только требование version = "0.1". См. комментарий на той строке в Cargo.toml.

Сборка

make dev          # debug build (fast incremental)
make install      # release build (realistic perf)

Или напрямую:

maturin develop
maturin develop --release

maturin develop компилирует Rust-расширение и устанавливает его в текущее активное Python-окружение — запускайте тесты из того же окружения.

Тесты

make test                          # full suite
pytest -v -k multiline             # filter by name
pytest -v tests/parse/test_loads.py  # single file

Модуль test_conformance.py запускает набор кросс-языковых фикстур из ktav-lang/spec, путь захардкожен как <repo>/spec/versions/0.8/tests (git submodule spec). Когда submodule не подтянут, conformance-тесты пропускаются, а не падают.

Conformance-набор параметризован по обоим backend-ам: одни и те же fixtures прогоняются и через нативное расширение, и через ktav.pure. CI дополнительно запускает отдельную job pure-mode, которая собирает pure wheel из packaging/pure и ставит его в свежий venv (KTAV_REQUIRE_PURE=1; tests/conftest.py роняет job, если ktav._core импортируется) и прогоняет установленный пакет через весь корпус скриптом scripts/check_installed_pure.py.

Lint + typecheck

make lint         # ruff check + ruff format --check
make typecheck    # mypy --strict
make rust-lint    # cargo fmt --check + cargo clippy -D warnings
make all          # lint + typecheck + rust-lint + test

В CI выполняются те же команды; прогоните make all локально перед пушем.

Pre-commit

pre-commit install
pre-commit run --all-files

Это подключает ruff, mypy, rustfmt, clippy и стандартные whitespace / EOL hooks к git commit.

Философия

Девиз Ktav: «будь другом конфига, а не его экзаменатором». Прежде чем предлагать новую Python-специфичную возможность, спросите себя:

  • Не добавляет ли это новое правило, которое читатель должен держать в голове?
  • Может ли это жить в пользовательском коде вместо библиотеки?
  • Не размывает ли это принцип «никакой магии в типах»?

Новые правила стоят дорого. Отклоняйте всё, что явно не на своём месте.

Языковая политика

Этот репозиторий участвует в общеорганизационной политике трёх языков (EN / RU / ZH). Каждый prose-документ живёт в трёх параллельных версиях — см. ktav-lang/.github/AGENTS.md для соглашения об именовании и правила «обновлять все три в одном коммите».

Если вы не владеете одним из языков, всё равно откройте PR на языке, которым владеете, отметьте нетронутые версии комментарием <!-- TODO: sync with <name>.md --> в начале — мейнтейнер или участник сообщества заполнит пробел до слияния.

Лицензия вкладов

Если вы явно не заявите иное, любой вклад, намеренно отправленный для включения в этот проект вами, как определено лицензией Apache-2.0, будет лицензирован на условиях MIT OR Apache-2.0 без каких-либо дополнительных условий.