Как участвовать¶

Полное руководство — CONTRIBUTING.md в репозитории. Коротко:

Установка¶

git clone https://github.com/DrobyshevDev/mlango
cd mlango
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
pre-commit install
pytest -q

Тесты идут офлайн — агенты используют провайдер echo, а метахранилище это SQLite во временном каталоге. Чтобы участвовать, API-ключ не нужен.

Перед pull request¶

ruff check mlango tests
ruff format mlango tests
mypy mlango
pytest -q --cov
mkdocs build --strict     # если правили документацию

Все пять проверок блокирующие в CI. pytest --cov требует локально ту же планку покрытия, что и на сервере: порог задан в pyproject.toml, поэтому невозможно быть зелёным на ноутбуке и красным в CI.

Пайплайн¶

.github/workflows/ci.yml (зеркало — .gitlab-ci.yml) запускает:

Задача	Что защищает
`lint`	ruff, ruff format, mypy без единой ошибки
`test`	тесты на Python 3.10–3.13, плюс macOS и Windows
`coverage`	порог из `[tool.coverage.report] fail_under`
`audit`	`pip-audit` по тому, что реально устанавливается
`quickstart`	`startproject` → migrate → train → evaluate → serve, по-настоящему
`transformers`	дообучает крошечный чекпоинт, чтобы этот бэкенд был проверен
`build`	wheel ставится в чистое окружение и везёт `py.typed`
`docs`	`mkdocs build --strict`
`ci`	одна агрегирующая проверка, падающая, если упала любая из выше

CodeQL запускается отдельно — на push и раз в неделю.

В защите ветки требуйте агрегирующую проверку CI, а не отдельные задачи. Если перечислять задачи по одной, добавленная позже окажется необязательной, и красная задача тихо перестанет блокировать merge.

Два правила про порог покрытия: поднимайте, когда число выросло, и никогда не опускайте, чтобы покрасить красную сборку в зелёный. Если что-то действительно нельзя покрыть — объясните почему в pull request.

На что мы смотрим¶

Ошибки, которые учат. Сообщение должно говорить, что не так, и что делать дальше:

raise FieldError(
    f"{opts.label} has no field named {name!r}. Available: {available}."
)

Комментарии объясняют «почему», а не «что». Что делает код, видно из кода; объясняйте ограничение, которого читатель не видит.

Тесты названы по гарантии, которую защищают — test_assignment_is_stable_when_rows_are_added, а не test_split.

Никаких новых обязательных зависимостей в ядре. Опциональные интеграции живут за extra в pyproject.toml с ленивым импортом.

Слои¶

Слой	Может импортировать	Не должен импортировать
`core/`	только стандартную библиотеку	что-либо ещё из mlango
`metastore/`	`core`	data, training, agents
`data/`, `training/`, `agents/`, `evals/`	`core`, `metastore`	друг друга
`admin/`, `serve/`	всё, но через `_meta`	—

Если нужен помощник, общий для слоёв, ему место в core — см. core/serialization.py, который существует именно поэтому.

Всё обобщённое читает _meta, а не проверяет конкретные типы. Именно это позволяет одной админке отображать датасеты, модели, агентов и оценки. Если какая-то возможность просит isinstance(obj, Dataset), поищите атрибут в _meta, который стоит прочитать вместо этого.

С чего начать¶

Перевести страницу документации — см. Перевод
Улучшить сообщение об ошибке, которое вас запутало
Добавить scorer в mlango/evals/scorers.py
Добавить бэкенд обучения (один файл плюс запись в настройках)
Добавить Source для формата, которым вы пользуетесь

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

Приложите вывод python manage.py check и минимальное объявление, которое воспроизводит проблему.