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

Upgrade guide

Upgrade guide

Эта страница — для пользователей, идущих с v0.13.x или раньше, которые хотят довести свой templates_dir до текущего YAML-first artifact-формата. Если ты уже на свежем srekit и templates dir пустая или fresh — эта страница не нужна, srekit templates init сразу делает новую раскладку.

Формат артефактов переехал с per-generator Go-template файлов (postmortem.md.tmpl + опц. postmortem.sections.yaml sidecar) на один YAML-артефакт на генератор (postmortem.yaml). Миграция шла инкрементально через v0.14.0 → v0.20.0 (1-2 генератора на релиз); v0.20.0 — cutover для embedded-набора. Твой templates_dir апгрейдится тем же способом каждый раз через srekit templates upgrade. Legacy-файлы в твоей dir остаются читаемыми и подсвечиваются stderr WARN, пока ты их не удалишь.

Журнал релиз-за-релизом (что изменилось когда и почему) — Migration history.

Быстрая проверка: где я?

ls твоей templates dir (путь — из ~/.srekit.yaml templates_dir: / $SREKIT_TEMPLATES_DIR / $XDG_CONFIG_HOME/srekit/templates):

  • Видишь *.yaml (postmortem.yaml, task.yaml, …) — ты на v1. Готово.
  • Видишь *.md.tmpl + возможно *.sections.yaml — у тебя legacy-файлы. Запускай upgrade-рецепт ниже.
  • Смесь (.yaml и .tmpl на тот же генератор) — ты начал; закончи, удалив legacy .tmpl после проверки, что новый .yaml рендерится правильно.

Upgrade-рецепт (v0.13.x → текущая)

Каждый шаг изолирован; можно остановиться после любого и перезапустить.

Порядок важен: templates migrate идёт первым, чтобы конвертнуть твои кастомизированные .tmpl в .yaml. Если запустить templates upgrade первым, он скаффолдит embedded .yaml, и templates migrate потом скипнет твои кастомизированные .tmpl (target уже существует) — твои кастомизации останутся проигнорированными.

TPL=~/.srekit/templates   # или где твоя dir

# 1. Конвертнуть кастомизированные .tmpl в твоей dir в .yaml. По умолчанию
#    dry-run печатает converted YAML; --apply пишет файлы. Конвертер копирует
#    template-выражения as-is — см. шаг переписывания ниже.
srekit templates migrate "$TPL"           # preview
srekit templates migrate "$TPL" --apply   # пишет <name>.yaml рядом с каждым .tmpl

# 2. Переписать data-shape ссылки внутри сгенерированного YAML.
#    Большинство генераторов переехало с .X на .Meta.X. Скипаем файлы,
#    которые УЖЕ используют .Meta.X (postmortem был на .Meta.X с v0.13.0 —
#    его sidecar driving типизированный доступ).
for f in "$TPL"/*.yaml; do
  grep -q '{{ \.Meta\.' "$f" && continue   # уже на .Meta.X — не трогаем
  sed -E -i '' 's/\{\{ \.([A-Z][a-zA-Z]*)/\{\{ .Meta.\1/g' "$f"
done
# rfc-специфично: function-call форма `{{ shortID .ID 8 }}` не ловится
# основным regex'ом — переписываем отдельно.
[ -f "$TPL"/rfc.yaml ] && sed -E -i '' 's/shortID \.ID/shortID .Meta.ID/g' "$TPL"/rfc.yaml

# (Linux/GNU sed: убери пустой `''` после `-i` — это BSD/macOS особенность.)

# 3. Притащить v1 артефакты, которые шипит бинарь и которых у тебя ещё нет
#    (например, ты пропустил какие-то генераторы в v0.13.x). Существующие
#    user-файлы не трогаются (3-way merge на следующих run'ах когда снапшоты появятся).
#    Orphaned snapshot'ы для legacy раскладок GC'шатся из .srekit-embedded/.
srekit templates upgrade "$TPL"

# 4. Проверить результат.
srekit templates validate "$TPL"
# OK    postmortem.yaml
# OK    task.yaml
# ...

# 5. Когда доверяешь новому YAML — render-тест, потом удаляй legacy.
#    Они не удаляются авто — это твои кастомизации.
srekit --templates-dir "$TPL" postmortem --title smoke --severity SEV-2 --stdout > /dev/null
rm "$TPL"/*.md.tmpl "$TPL"/*.sections.yaml 2>/dev/null

Подсказки:

  • Section ID — часть structured --json контракта; если конвертер slugify'нул заголовок секции неудобно (например bilingual heading с abbreviation), открой YAML и переименуй id: перед тем как полагаться на --json consumers.
  • Секции с Go-template control flow ({{ if }} / {{ range }} / {{ with }}) обрамляются git merge-стайл diff-маркерами — конвертер не переводит control flow в типизированный sections-словарь. Резолви руками.
  • header_body: — freeform-Markdown escape hatch; используй для blameless-callout'ов, custom-blockquote'ов, всего что не лезет в типизированные секции. (Для postmortem-style .tmpl файлов, которые заканчиваются {{ range .Sections }} loop'ом, конвертер корректно опускает header_body начиная с v0.26.0.)
  • license_*.tmpl пропускаются; license-bodies зашиты в бинарь с v0.14.0.

Изменения JSON shape по версиям

srekit <generator> --json прошёл через две breaking shape-changes. Мигрируй jq-consumers соответственно:

Откуда → Куда Изменение shape jq-миграция
0.12.x → 0.13.0 плоское {title, severity, …} → {meta, sections} jq '.title' → jq '.meta.title'
0.13.x → 0.20 bootstrap envelope (sections: [{id:"body", body:<markdown>}]) → structured per-artifact sections jq '.sections[0].body' → jq '.sections[] | select(.id=="<id>").body'

Per-section ID — в internal/tmpl/templates/<name>.yaml в репо бинаря. Structured-контракт стабилен с v0.20.0.

--template FILE

Флаг теперь license-only. Остальные генераторы (postmortem, task, retro, slo, ebp, capacity, incident, rfc, runbook, oncall-report, changelog) отвечают Error: unknown flag: --template. Это v0.22.0-cleanup флага, который стал silent no-op после миграции каждого генератора на artifact path.

Per-artifact кастомизация в v1-модели — положить <name>.yaml в templates_dir. См. Custom templates workflow для полного цикла.

Границы стабильности

Stable contracts (не изменятся без major version bump):

  • Поля схемы <name>.yaml: version, frontmatter, title, meta_bullets, header_body, sections. Новые поля могут добавляться; существующие не удаляются до 2.0.
  • Внешняя форма --json ({meta, sections}) и форма секции ({id, title, type, required, body}).
  • Словарь section type (text / list / table).
  • Имена per-command meta-полей (добавление — minor; удаление — breaking).
  • CLI-флаги, показанные в --help каждой команды.

Совместимость сохранена, кандидаты на удаление в v2.0:

  • Legacy .tmpl loader path (Loader.Parse) для user-файлов в templates_dir. Работает с stderr WARN.
  • Legacy .sections.yaml sidecar parser (sections.ParseManifest) — используется templates validate / templates migrate для чтения pre-v0.14 dirs.

Ещё не стабильно (может измениться в 1.x или 2.0):

  • Поле frontmatter — free-form map. Возможно появится типизированная JSON Schema; breaking только для авторов, завязанных на free-form структуру.
  • Точная формулировка stderr WARN для legacy .tmpl файлов.

Troubleshooting

WARN: <file> in <dir> is a legacy pre-v1.0 format and is being ignored. — Legacy .tmpl или .sections.yaml лежит рядом с v1 <name>.yaml в твоей dir. Мигрируй по рецепту выше; legacy-файлы не удаляются авто (это твои кастомизации). WARN глушится через --quiet.

Error: load <name>.yaml: ... — Embedded-артефакт отсутствует или user-dir версия malformed. Запусти templates validate чтобы увидеть parse-error.

Error: parse <name>.yaml: unknown type "..." — Твой user-dir артефакт объявил секцию с type: который бинарь не знает. Поддерживаемые типы: text, list, table. Поправь YAML.

Section heading показывает raw template syntax ({{ .Meta.X }}) — pre-v0.20.0 srekit не template-evaluate'ил section titles. Обнови бинарь до v0.20.0+ или используй статичные titles.

См. также