Перейти к содержанию

Разработка

Quarshell состоит из независимых Git-репозиториев и Go-модулей версии 1.27. В локальном workspace checkouts располагаются рядом. Корню workspace не нужен Git-репозиторий; выполняйте Git-команды внутри изменяемого модуля.

Go workspace

Связывайте соседние модули через go.work. Локальные replace должны находиться в нём, а не в публикуемых go.mod. Для workspace-модулей указывайте версию:

go work edit -replace=github.com/KLORQ/quarshell-core@v0.4.2=./quarshell-core
git -C quarshell-cli status

Версии должны соответствовать manifests соседних checkouts. Перед релизом также проверяйте сборку без workspace после публикации версий зависимостей.

Корневой Taskfile.yml запускает общие проверки. После добавления или переименования Go-модуля выполните task workspace:sync; для проверки модулей — task check; для закреплённого контракта OpenShell — task compat:pin-check, task compat:proto и task compat:inventory. Перед публикацией запускайте тесты из checkout каждого модуля.

Проверка proto использует checkout исходников точного коммита OpenShell. Подготовьте его командой bash tools/fetch-openshell-upstream.sh: скрипт сверит существующий checkout с tools/upstream/UPSTREAM_SHA или скачает закреплённый коммит.

Выпуски

Модули используют теги semantic versioning. Alpha, beta и release candidate — предварительные выпуски. Nightly-сборки CLI запускаются вручную и сейчас не публикуются на странице Releases. У каждого модуля свой выпуск. При изменении публичного пути или API сначала выпустите зависимости, обновите версии у потребителей и проверьте чистую сборку с GOWORK=off без локальных replace. Опубликованные теги не переписывайте.

Все Go-модули пока имеют нестабильный API и остаются в серии 0.x. Новые пути модулей начинаются с v0.1.0; для пути с уже опубликованными тегами используется следующий свободный неизменяемый 0.x тег. Не заявляйте стабильность API и не переписывайте опубликованные теги. Сначала публикуйте зависимости, обновляйте требования и workflow refs, затем проходите consumer gate с GOWORK=off. У каждого модуля своя версия; сверяйтесь с его go.mod и tools/modules.lock. Python пока не опубликован в PyPI.

Локальный каталог logging-модуля называется quarshell-slogx, но опубликованный путь пока остаётся github.com/KLORQ/quarshell-slogx. Публичный путь следует менять только вместе с новым репозиторием и проверенной миграцией потребителей.

Правила ревью

  • Объявляйте маленькие интерфейсы у потребителя; скрывайте внутренние helpers.
  • Для публичных map используйте предметные алиасы, например SDK Credentials и Labels, сохраняя совместимость с обычными map.
  • Возвращайте ошибки, влияющие на корректность. Объясняйте намеренно отброшенные ошибки; Go не требует комментария к каждому blank identifier.
  • Храните общие пути, порты, host aliases и endpoints в core/defaults.
  • Применяйте стандартную модернизацию через go fix, проверяя изменения поведения. Изменения JSON требуют отдельной проверки совместимости.

Проверяйте форматирование, сборку, race tests, vet, платформенные сборки и линтеры репозитория. Документацию проверяйте командой mkdocs build --strict.

Inference endpoints

В provider record можно задать config.base_url: HTTP(S) URL с host и без встроенных credentials. Известные типы используют свои defaults; неизвестные не перенаправляются на OpenAI. DeepInfra использует собственный endpoint. Политика sandbox должна разрешать указанное назначение.