Упрощенные рабочие процессы релизов с Changesets

Публикация npm-пакетов не должна требовать пользовательских скриптов, ручного изменения версий или запоминания того, какие пакеты изменились с момента последнего релиза. Тем не менее, многие команды все еще собирают воедино хрупкие процессы релизов, которые ломаются в самый неподходящий момент.

Changesets решает эту проблему, фиксируя намерение о релизе в момент внесения изменений, а затем автоматизируя все остальное. В этой статье рассматривается, как построить современный рабочий процесс релизов с Changesets — включая доверенную публикацию в npm, версионирование монорепозиториев с Changesets и релизы пакетов через GitHub Actions — без бремени поддержки.

Основной рабочий процесс релизов с Changesets

Рабочий процесс состоит из трех фаз:

1. Контрибьюторы добавляют файлы changeset, описывающие, что изменилось и насколько это значимо (patch, minor, major)
2. CI создает PR для версионирования, который агрегирует все changesets в изменения версий и записи в changelog
3. Слияние PR запускает публикацию в npm с правильным подтверждением происхождения

Каждый changeset — это markdown-файл в .changeset/, содержащий frontmatter, который указывает затронутые пакеты и тип изменения версии по semver, плюс человекочитаемое описание. Когда существует несколько changesets, Changesets вычисляет наивысшее необходимое изменение версии для каждого пакета — два minor-изменения не превращаются в два minor-повышения версии.

Для монорепозиториев это имеет большое значение. Changesets автоматически обрабатывает обновления внутренних зависимостей, когда один пакет workspace зависит от другого, который выпускается.

Релизы пакетов через GitHub Actions: современный подход

Большинство руководств показывают workflows с использованием секретов NPM_TOKEN. Этот подход работает, но несет риски безопасности — долгоживущие токены могут утечь и требуют ручной ротации.

Доверенная публикация в npm с использованием OIDC-токенов теперь является предпочтительным методом. Вместо хранения учетных данных ваш workflow в GitHub Actions запрашивает краткосрочный токен напрямую у npm во время шага публикации. Токен существует только для этой задачи и не может быть извлечен или использован повторно.

Чтобы включить это:

1. Свяжите ваш npm-пакет с вашим GitHub-репозиторием в настройках пакета на npm
2. Настройте ваш workflow с разрешением id-token: write
3. Убедитесь, что включено подтверждение происхождения (npm может генерировать его автоматически для доверенных издателей или через флаг --provenance в новых версиях CLI)

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

Текущие ограничения, которые нужно знать: доверенная публикация в npm требует публичных репозиториев. Приватные репозитории все еще нуждаются в устаревшем подходе с NPM_TOKEN. Кроме того, официальный changesets/action имеет развивающуюся поддержку OIDC — проверьте текущую документацию для последних паттернов интеграции.

Версионирование монорепозиториев с Changesets

Changesets был разработан для монорепозиториев с самого начала. Ключевые опции конфигурации в .changeset/config.json управляют поведением для множества пакетов:

• linked: группирует пакеты, которые всегда должны иметь одинаковый номер версии
• fixed: похож на linked, но все пакеты обновляются вместе, даже если изменился только один
• updateInternalDependencies: контролирует, получают ли зависимые пакеты patch-обновления, когда обновляются их зависимости

Когда контрибьютор запускает CLI Changesets в монорепозитории, он выбирает, какие пакеты затрагивает его изменение. PR версионирования затем показывает точно, какие пакеты будут выпущены и в каких версиях.

Распространенные проблемы в CI

Проблемы с правами доступа вызывают большинство сбоев workflow. GitHub-токен должен иметь права на запись для создания PR и отправки тегов. Для публикации в npm убедитесь, что ваш токен (или конфигурация OIDC) имеет права на публикацию всех пакетов в вашем scope.

Конфликты автоматизации PR возникают, когда правила защиты веток блокируют бота от отправки коммитов с версиями. Либо разрешите боту GitHub Actions обходить защиту, либо используйте выделенный аккаунт бота с соответствующими правами.

Порядок публикации множества пакетов имеет значение, когда пакеты зависят друг от друга. Changesets обрабатывает это автоматически, но сбои сети в середине публикации могут оставить ваш монорепозиторий в несогласованном состоянии. changesets/action включает логику повторных попыток, но понимание этого режима отказа помогает с восстановлением.

Забытые changesets — самая распространенная ошибка контрибьюторов. Changeset bot комментирует PR, в которых отсутствуют changesets, но вы также можете добавить проверки CI, которые завершаются с ошибкой, когда changesets требуются, но отсутствуют.

Структурирование вашего workflow сегодня

Большинство команд запускают Changesets action при каждом push в main. Action либо открывает, либо обновляет PR “Version Packages”, когда существуют невыпущенные changesets, либо публикует пакеты, когда PR версионирования сливается.

Это создает естественный ритм релизов: вливайте функции в течение недели, затем сливайте PR версионирования, когда вы готовы к релизу. Никакого ручного редактирования версий, никакого забывания обновить changelog, никакой публикации не тех пакетов.

Заключение

Хорошо настроенный рабочий процесс релизов с Changesets устраняет когнитивную нагрузку при релизах пакетов. Контрибьюторы заранее декларируют намерения, CI обрабатывает координацию, а доверенная публикация в npm обеспечивает безопасные, проверяемые артефакты.

Начните с настройки для одного пакета, чтобы понять процесс, затем расширяйте на монорепозитории по мере необходимости. Первоначальные инвестиции в конфигурацию быстро окупаются снижением беспокойства о релизах и меньшим количеством моментов “ой, не та версия”.

Часто задаваемые вопросы

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.