Перевод английского нормативного контракта, сверенный с оригиналом в ревизии 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не является новой редакцией спецификации.
migrate-prepare читает набор документов и создаёт новый каталог за его пределами. Каталог не должен существовать. Команда не открывает закрытое хранилище и не изменяет исходные документы.
okf migrate old-bundle --to 0.2 --format json
okf migrate-prepare old-bundle --output-dir ../migration-inputs --format json
Каталог содержит:
citation-mappings.json: точный формат массива --citation-mappings с закрытым набором полей. Помощник заполняет селекторы legacy_number и точный legacy_entry, полученные парсером. Все значения source_id изначально пусты; перед предварительным просмотром выберите и укажите реальный идентификатор источника. Предложенные заголовки и ресурсы автоматически не принимаются.generated-at.json: точный формат массива --generated-at с закрытым набором полей. Документы со старым type, но без timestamp и generated, получают пустое значение at. Введите реальный исторический момент времени RFC3339 с Z или явным смещением. Не подменяйте время создания содержимого временем миграции.preparation-report.json: SHA-256 исходных данных, диапазоны байтов, возможные значения заголовка и ресурса, а также неразрешённые случаи. Это рекомендации, а не входные данные применения или подтверждение разрешения. generated_by пуст, потому что только вызывающая сторона знает создателя; timestamp_policy=preserve и timestamp_conflict=reject описывают существующую политику CLI.Разрешив замечания отчёта и заполнив шаблоны, выполните предварительный просмотр и применение через существующий механизм миграции:
okf migrate old-bundle --to 0.2 --actor human:author \
--citation-mappings ../migration-inputs/citation-mappings.json \
--generated-at ../migration-inputs/generated-at.json \
--prepared-source-sha256 HASH_FROM_REPORT --format json
okf migrate old-bundle --to 0.2 --actor human:author \
--citation-mappings ../migration-inputs/citation-mappings.json \
--generated-at ../migration-inputs/generated-at.json \
--prepared-source-sha256 HASH_FROM_REPORT --write --format json
--prepared-source-sha256 отклоняет изменившийся набор до построения плана. После любого изменения исходных данных заново создайте каталог под другим именем. Обычный механизм предварительного просмотра и применения по-прежнему проверяет собственную ревизию, разрешение источников, контрольную сумму запроса и подтверждение плана. Пустые значения source_id или at отклоняются строгими загрузчиками входных данных, поэтому неподтверждённый шаблон нельзя применить. Если отдельные моменты времени для документов не нужны, generated-at.json содержит []; флаг можно не указывать.
Например, две идентичные ненумерованные цитаты невозможно выбрать независимо друг от друга в текущем DTO сопоставлений. Отчёт помечает обе как duplicate or unrepresentable parser-owned citation selectors — дублирующиеся или непредставимые селекторы цитат, определённые парсером — и не включает их в шаблон. Вызывающая сторона должна устранить неоднозначность в исходных данных либо использовать поддерживаемый уникальный селектор, затем повторить подготовку. Нераспознанный текстовый абзац внутри # Citations попадает в отчёт с диапазоном байтов; он никогда не удаляется молча. Псевдоцитата внутри блока кода отмечается как непрозрачное содержимое и не преобразуется в источник.
Если документ уже содержит структурированные sources вместе со старым разделом # Citations, отчёт возвращает sources_citations_conflict и не включает сопоставление для этого документа. Планировщик миграции также блокирует такое смешанное представление; вызывающая сторона должна явно согласовать его перед повторной подготовкой.
Начальный UTF-8 BOM перед --- отмечается как leading_bom_unsupported в байтах 0–3. Парсер, требующий точного оформления метаданных, не распознаёт эту начальную строку; миграция прекращается без изменений, сохраняя байты документа. Байты BOM внутри корректного текста документа или непрозрачных значений YAML сохраняются существующим механизмом изменения.
Помощник не экспортирует подтверждение миграции и не выполняет изменений. Заблокированный предварительный просмотр остаётся заблокированным до выполнения необходимых ручных действий.