Версии

Проект хранит рядом с другими зависимостями одну запись: идентификатор выпуска Framework, а для каждого подключённого пакета продукта — его квитанцию, а также адреса, по которым они подключены. Удобная форма — файл блокировки проекта, например simai-framework.lock.json в корне репозитория проекта. Формат этого файла выбирает проект: Framework его не читает. Если файла блокировки нет, выпуск определяют по адресу, с которого страница подключает distr/: по версии пакета npm в адресе CDN (поле simai пакета называет выпуск и коммит, см. Пакет npm) или по полному коммиту, из которого взята своя копия, — и сразу записывают его в файл блокировки; номер из VERSION выпуск не определяет. Пример показывает минимальное содержание для выпуска ui-106d5901f8c3 с пакетом продукта larena, собранным для этого выпуска:

{
  "framework": {
    "release": "ui-106d5901f8c3",
    "commit": "106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4",
    "npm": "@simai-studio/ui@5.20261019.1559",
    "distr_archive_sha256": "<runtime_sources.core.archive_sha256 из записи о выпуске>",
    "distr_tree": "<runtime_sources.core.runtime_tree из записи о выпуске>"
  },
  "packages": {
    "larena": {
      "receipt": "<путь к квитанции пакета>",
      "source_revision": "5f33ba576aebde377d5195ec71836eb4430aa84d",
      "framework": "ui-106d5901f8c3",
      "manifest_sha256": "<output.manifest_sha256 из квитанции>"
    }
  }
}

Поле commit — полный коммит выпуска из записи о выпуске (runtime_sources.core.commit, см. Выпуск и запись о выпуске): по нему берут свою копию поставки, идентификатор выпуска — не тег git. Поле npm — пакет и версия, которые стоят в адресах CDN; версия получается из коммита выпуска (см. Пакет npm). Проекту со своей копией это поле не нужно.

Значения в угловых скобках — места, которые проект заполняет настоящими значениями; в файле блокировки угловых скобок не остаётся. distr_archive_sha256 и distr_tree переписывают из записи о выпуске, manifest_sha256 — из поля output.manifest_sha256 квитанции пакета.

Что важно заметить:

• человеку достаточно идентификатора выпуска и имени пакета, инструментам — точных ревизий и хешей;
• поле framework у пакета совпадает с выпуском Framework, который закреплён рядом; source_revision — поле package_source.revision квитанции, коммит репозитория simai/larena-ui, из которого собран пакет;
• файл блокировки проекта — не то же самое, что /ai/framework-lock.json сайта документации: тот называет выпуск, который описывает документация, а не выпуск проекта (см. Машиночитаемые источники).

Контрольные суммы архивов поставки Framework и идентификаторы деревьев git берутся из записи о выпуске (см. Выпуск и запись о выпуске), контрольные суммы файлов пакета — из его квитанции (см. Пакеты компонентов продуктов).

Правила:

1. Поставка меняется только целиком, на другой выпуск; файлы двух выпусков не смешиваются.
2. Выпуск Framework и пакет продукта закрепляются вместе. Квитанция пакета называет ровно один выпуск Framework, и проект подключает именно его.
3. На новый выпуск Framework проект с пакетом продукта переходит вместе со сборкой пакета, квитанция которой называет этот выпуск Framework. Пока такой сборки нет, проект остаётся на прежнем выпуске.
4. Если проект использует только Core и утилиты, выпуск всё равно закрепляется точно.

Список изменений поставки ведётся в файле CHANGELOG.md репозитория ui, а изменения, которые требуют правки проекта, — в журнале изменений (см. Журнал изменений).