Версиями и списками изменений управляют changesets. Публикация остаётся бездействующей, пока не настроен токен, поэтому учёт в любом случае корректен.

Добавление changeset

Любое изменение, затрагивающее публикуемый пакет, требует его:

pnpm changeset

Он спрашивает, какие пакеты изменились и что это для каждого — patch, minor или major, — а затем пишет markdown-файл в .changeset/. Коммитьте этот файл вместе с кодом.

.changeset/quick-pandas-shave.md

---
'@handbooks/analyzer': minor
'@handbooks/cli': patch
---

Add a generic-tier Elixir spec and surface it in `--lang`.

Пишите описание для читателя списка изменений, а не для ревьюера: что изменилось снаружи, а не как.

Чему он нужен

Изменение	Changeset?
Новая возможность или флаг	✅ minor
Исправление ошибки в уже поставленном поведении	✅ patch
Ломающее изменение API или CLI	✅ major
Новый языковой адаптер	✅ minor
Документация, тесты, CI, внутренние рефакторинги	❌
Что угодно под `docs/`	❌

Процесс релиза

Влейте в `main` при наличии changesets

Workflow Release открывает (или обновляет) pull request «Version Packages».

Он применяет каждый ожидающий changeset: поднимает версии, пишет CHANGELOG.md каждого пакета и удаляет израсходованные файлы changeset. Прочитайте дифф списка изменений — это и есть заметки о релизе.

Влейте его

Это публикует пакеты в npm.

Публикация бездействует, пока нет NPM_TOKEN

Без настроенного секрета шаг публикации ничего не делает. Версионирование и списки изменений при этом по-прежнему корректны — поэтому учёт верен независимо от того, публикуются ли пакеты на самом деле, а включение публикации позже не потребует переписывания истории.

Как сделать это вручную

pnpm release:status      # what is pending
pnpm release:version     # apply changesets, bump, write changelogs
pnpm release:publish     # build, then changeset publish

release:version также запускает pnpm install --lockfile-only, потому что поднятые версии пакетов рабочего пространства меняют lock-файл.

Перед релизом

pnpm check:all

Это pnpm check плюс два шлюза, обращённых к публикации:

check:packaging — publint и @arethetypeswrong/cli по каждому пакету. Ловит неверную карту exports, отсутствующую декларацию типов, опасность двойного пакета.
check:install — упаковывает все одиннадцать тарболов, устанавливает их обычным npm во временный каталог и прогоняет по ним CLI. Это сильнейшая из существующих проверок dist: она задействует настоящую публикуемую поверхность, а не симлинки рабочего пространства.

Они упаковывают одиннадцать тарболов, поэтому им место в CI и перед релизом, а не в каждом локальном цикле.

Происхождение (provenance)

Provenance в npm требует поля repository, указывающего на публичный репозиторий, в каждом манифесте. Поскольку это двенадцать правок, где directory каждый раз разный:

node scripts/set-repo-url.mjs https://github.com/OWNER/REPO
node scripts/set-repo-url.mjs --check

Для этого репозитория уже настроено; команда здесь для форка и для того дня, когда репозиторий переедет.

Скрипт идемпотентен — запустите его снова после переезда репозитория. Он намеренно не подключён к pnpm check: пока у репозитория нет публичного URL, сверяться не с чем, а шлюз, падающий на свежем клоне, приучает людей игнорировать шлюзы.

Политика версионирования

Обычный semver, с двумя конвенциями, которые стоит проговорить:

Флаги CLI — это публичный API. Удаление или переименование флага — это major. Добавление — minor.
Схемы артефактов версионируются отдельно своим полем version. Изменение схемы, делающее недействительными существующие рабочие каталоги, — это major для пакетов, которые их читают, и в changeset нужна пометка об этом: механизма миграции артефактов нет, поэтому «удалите рабочий каталог и перегенерируйте» должно быть приемлемым ответом.

Выпуск релиза