Changesets로 모노레포 패키지 릴리즈 관리하기

처음 fluo의 패키지를 배포할 때는 모든 과정을 수동으로 처리했다. 이후 GitHub Actions를 도입하면서 실행 과정은 어느 정도 자동화했지만, 여전히 중요한 판단은 사람의 기억에 남아 있었다.

• 패키지 A를 수정했는데, A에 의존하는 패키지 B, C도 버전을 올려야 할까?
• 이번 릴리즈에 어떤 변경사항이 들어갔는지 CHANGELOG는 누가 정리할까?
• npm publish를 잘못된 버전으로 실행하면 어떻게 될까?

자동화된 것은 배포 명령 실행뿐이었다. 어떤 패키지를 올릴지, 의존 패키지 버전은 어떻게 맞출지, CHANGELOG에는 무엇을 남길지는 여전히 사람이 판단해야 했다.

패키지가 대여섯 개라면 감당할 수 있었을지도 모른다. 하지만 이 글을 쓰는 시점에 fluo의 패키지는 39개다. 배포 대상에서 빠지는 패키지가 생기고, 버전 불일치가 발생하고, CHANGELOG는 “bump version” 같은 의미 없는 기록으로 채워지기 시작했다.

그래서 fluo에 Changesets를 도입했다.

Changesets가 해결하는 문제

Changesets의 핵심은 버전 결정을 배포 직전이 아니라 PR 시점으로 앞당기는 것이다. 기능을 추가하거나 버그를 고칠 때, 이 변경이 어떤 패키지에 영향을 주는지, semver 기준으로 major, minor, patch 중 무엇인지 함께 기록한다. 이 기록은 .changeset/{slug}.md 파일로 저장되고, 나중에 버전 bump와 CHANGELOG 생성의 입력이 된다.

즉, 개발자는 변경 의도를 선언하고, Changesets는 반복 작업을 처리한다.

• 어떤 패키지의 버전을 올릴지 결정
• 내부 의존 패키지 버전 전파
• package.json 버전 수정
• CHANGELOG.md 생성
• publish 대상 패키지 선별

배포 시점에는 더 이상 기억을 더듬을 필요가 없다. PR과 함께 쌓인 changeset 파일을 기준으로 릴리즈가 진행된다.

설치와 초기화

pnpm add -D @changesets/cli
pnpm changeset init

초기화하면 .changeset/ 폴더와 config.json이 생긴다. 별도 서버나 외부 서비스는 필요 없다.

Changesets는 워크스페이스 루트의 패키지 목록을 읽는다. pnpm 기준으로 pnpm-workspace.yaml에 packages가 올바르게 정의되어 있어야 한다. 확인은 다음 명령으로 할 수 있다.

pnpm changeset status

패키지 목록이 비어 있다면 Changesets 문제가 아니라 워크스페이스 설정 문제일 가능성이 높다.

알아야 할 파일 세 가지

1. .changeset/{slug}.md

가장 자주 다루는 파일이다.

---
"@fluojs/http": minor
"@fluojs/core": patch
---

Add `@Route` prefix support for controller-level path prefixes.

Patch `@fluojs/core` to align internal metadata store with the new routing contract.

프론트매터에는 어떤 패키지를 어떤 수준으로 올릴지 적고, 본문에는 CHANGELOG에 들어갈 설명을 쓴다. 파일명은 자동 생성되며 중요하지 않다.

2. .changeset/config.json

Changesets 설정 파일이다.

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@fluojs/playground"]
}

자주 보는 값은 이 정도다.

• access: npm 공개 범위. scoped 패키지를 공개 배포하려면 "public"이 필요하다.
• updateInternalDependencies: 내부 의존성 전파 수준. 보통 "patch"를 둔다.
• ignore: 배포하지 않을 패키지 목록.
• commit: changeset version 실행 시 변경사항을 자동 커밋할지 여부.

3. .changeset/pre.json

pre-release 모드일 때만 생긴다. 예를 들어 beta 모드에 들어가면 이런 파일이 만들어진다.

{
  "mode": "pre",
  "tag": "beta",
  "initialVersions": {
    "@fluojs/core": "0.9.0",
    "@fluojs/http": "0.4.2"
  },
  "changesets": []
}

이 파일이 있으면 1.0.0-beta.1, 1.0.0-beta.2 같은 버전이 생성된다. 없으면 일반 릴리즈 모드다.

릴리즈 흐름

1. 기능 개발
   └─ pnpm changeset 실행
      └─ .changeset/some-slug.md 생성

2. PR 오픈 후 main 머지

3. GitHub Actions 실행
   └─ changesets/action이 changeset 파일 감지
      └─ "Version Packages" PR 생성 또는 업데이트
         ├─ package.json 버전 bump
         └─ CHANGELOG.md 갱신

4. "Version Packages" PR 머지

5. GitHub Actions 다시 실행
   └─ npm publish
      ├─ 변경된 패키지만 publish
      ├─ GitHub Release 생성
      └─ git 태그 생성

개발자가 직접 하는 일은 보통 두 가지다.

1. PR에 changeset 파일을 포함한다.
2. 릴리즈할 준비가 됐을 때 "Version Packages" PR을 머지한다.

"Version Packages" PR은 github-actions[bot]이 자동으로 열고 유지한다. main에 changeset 파일이 추가될 때마다 PR도 갱신된다. 이 PR을 보면 어떤 패키지가 얼마나 올라가는지, CHANGELOG에 어떤 내용이 들어가는지 미리 확인할 수 있다.

GitHub Actions 연동

fluo에서는 changesets/action을 사용해 릴리즈를 자동화한다.

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      id-token: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          registry-url: https://registry.npmjs.org

      - run: pnpm install --frozen-lockfile

      - name: Create Release Pull Request or Publish
        uses: changesets/action@v1
        with:
          publish: pnpm release
          version: pnpm version-packages
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

이 워크플로우는 두 상황을 나눠 처리한다.

• .changeset/*.md가 있으면 "Version Packages" PR을 생성하거나 업데이트한다.
• "Version Packages" PR이 머지되면 pnpm release를 실행해 npm 배포와 GitHub Release 생성을 진행한다.

permissions도 중요하다.

• contents: write: GitHub Release와 git 태그 생성에 필요
• pull-requests: write: Version Packages PR 생성과 업데이트에 필요
• id-token: write: npm provenance 생성에 필요

package.json에는 보통 이렇게 둔다.

{
  "scripts": {
    "release": "pnpm build && changeset publish",
    "version-packages": "changeset version"
  }
}

fetch-depth: 0도 빼지 않는 게 좋다. Changesets가 태그를 만들거나 이전 상태를 비교할 때 전체 git 히스토리가 필요할 수 있다.

changeset 파일 만들기

pnpm changeset

CLI는 대략 이런 흐름으로 진행된다.

Which packages would you like to include?
Which packages should have a major bump?
Which packages should have a minor bump?
Please enter a summary for this change.

끝나면 .changeset/ 아래에 Markdown 파일이 생긴다. 이 파일을 코드 변경과 함께 커밋하면 된다.

git add .changeset/curvy-buses-lie.md
git commit -m "feat(http): add timeout option to HTTP client"

직접 작성해도 된다.

---
"@fluojs/cli": minor
"@fluojs/platform-fastify": patch
---

CLI에 `--watch` 플래그를 추가했다. 기존 명령어는 그대로 동작하며, `--watch`는 선택적으로 사용할 수 있다.

`platform-fastify` 어댑터는 watch 모드에서 서버를 재시작하지 않고 라우트만 다시 등록하도록 수정했다.

changeset 본문은 그대로 CHANGELOG에 들어간다. 그래서 커밋 메시지처럼 쓰기보다, 사용자가 읽을 릴리즈 노트라고 생각하고 쓰는 편이 좋다.

Semver 고르는 기준

기준은 단순하게 잡는 게 좋다.

• 기존 함수 시그니처에서 파라미터를 제거하거나 타입을 바꿈: major
• 기존 함수에 optional 파라미터를 추가: minor
• 새 API나 새 export 추가: minor
• 외부 동작이 같은 내부 구현 변경: patch
• 오탈자, 주석, 문서성 수정: patch

헷갈리면 일단 patch로 두고 PR 리뷰에서 조정한다. "Version Packages" PR이 머지되기 전에는 changeset 파일을 수정하면 된다.

0.x 단계에서는 breaking change를 보통 minor로 처리한다. 1.0.0부터 semver 계약을 본격적으로 지키겠다는 의미가 강해지기 때문이다. Changesets를 쓰면 이 판단이 PR마다 드러난다. 이 패키지가 stable API를 약속할 준비가 됐는지 자연스럽게 고민하게 된다.

내부 의존성 전파

Changesets를 쓰면서 가장 체감이 큰 부분이다.

packages/
├── core/               @fluojs/core               v1.2.0
├── http/               @fluojs/http               v0.5.0  (core에 의존)
└── platform-fastify/   @fluojs/platform-fastify   v0.3.0  (core, http에 의존)

@fluojs/core에만 minor changeset을 만들고 changeset version을 실행하면 다음처럼 전파된다.

@fluojs/core             1.2.0 → 1.3.0   (minor, 직접 선언)
@fluojs/http             0.5.0 → 0.5.1   (patch, 자동 전파)
@fluojs/platform-fastify 0.3.0 → 0.3.1   (patch, 자동 전파)

config.json의 설정 때문이다.

{
  "updateInternalDependencies": "patch"
}

결과적으로 의존 패키지의 package.json도 함께 바뀐다.

- "version": "0.5.0",
+ "version": "0.5.1",
  "dependencies": {
-   "@fluojs/core": "workspace:^1.2.0"
+   "@fluojs/core": "workspace:^1.3.0"
  }

상위 패키지가 올라갔으니, 그 패키지를 의존하는 downstream 패키지도 최소 patch로 올라간다. 사람이 의존 그래프를 따라가며 하나씩 수정할 필요가 없다.

fixed와 linked도 있다. fixed는 여러 패키지를 항상 같은 버전으로 묶고, linked는 bump 수준만 맞춘다. 하지만 대부분의 경우에는 updateInternalDependencies: "patch"만으로 충분했다.

CHANGELOG 생성 방식

changeset version을 실행하면 각 패키지의 CHANGELOG.md가 갱신된다.

# @fluojs/http

## 0.5.1

### Patch Changes

- Updated dependencies
  - @fluojs/core@1.3.0

## 0.5.0

### Minor Changes

- abc1234: Add timeout option to HTTP client

  `HttpClient` 생성자에 `timeout` 옵션이 추가됐다.

  ```ts
  const client = new HttpClient({ timeout: 5000 });

CHANGELOG는 커밋 단위가 아니라 changeset 파일 단위로 생성된다. 한 PR에 커밋이 열 개 있어도, CHANGELOG에는 changeset 본문만 들어간다. 커밋 메시지는 개발자를 위한 기록이고, CHANGELOG는 패키지 사용자를 위한 문서이기 때문이다.

자동 생성된 항목에 붙는 짧은 커밋 해시는 changeset 파일이 추가된 커밋을 가리킨다. 나중에 변경 출처를 추적할 때 유용하다.

CHANGELOG를 직접 수정하기보다 changeset 본문을 잘 쓰는 편이 낫다. 다음 실행 때 자동 생성 결과로 덮일 수 있기 때문이다.

<p></p>

## Pre-release 모드

`.changeset/pre.json`이 있으면 pre-release 모드다. 이 모드에서는 버전이 `1.0.0-beta.1`, `1.0.0-beta.2`처럼 올라간다.

pre-release는 주로 두 상황에서 쓴다.

1. 큰 breaking change를 stable 전에 먼저 배포하고 싶을 때
2. 처음 공개하는 패키지를 beta로 배포하고 싶을 때

![](https://ayden-blog-assets.s3.ap-northeast-2.amazonaws.com/prod/uploads/inline/1777295319563-39a89682-7d1e-42e3-ae45-c70b58fd03b2-___________2026-04-27______10.07.03.png)

진입과 탈출은 명령으로 처리한다.

```bash
pnpm changeset pre enter beta
pnpm changeset pre exit

흐름은 다음과 같다.

v1.0.0-beta.1
v1.0.0-beta.2
v1.0.0-beta.3
v1.0.0

beta 대신 alpha, rc 같은 태그도 쓸 수 있다.

pre-release 모드에서 주의할 점이 있다. "Version Packages" PR이 머지되어도 .changeset/*.md 파일이 바로 삭제되지 않는다. 버그가 아니라 의도된 동작이다.

처리된 changeset slug는 pre.json의 changesets 배열에 기록된다. 이렇게 해야 beta 사이클이 끝난 뒤 stable로 전환할 때 같은 changeset이 중복 반영되지 않는다. pre exit 후 stable 릴리즈가 만들어질 때 changeset 파일과 pre.json이 정리된다.

자주 생기는 혼란

changeset 파일을 빠뜨리고 PR을 머지했다

다음 PR에서 해당 변경을 포함해 changeset을 만들면 된다. Changesets는 커밋이 아니라 .changeset/*.md 파일을 기준으로 동작한다.

Version Packages PR이 열려 있는데 새 changeset을 추가했다

괜찮다. 봇이 기존 PR을 자동으로 업데이트한다.

minor로 만들었는데 major가 필요했다

publish 전이라면 changeset 파일의 프론트매터를 수정하면 된다.

- "@fluojs/http": minor
+ "@fluojs/http": major

이미 publish됐다면 기존 버전은 수정할 수 없다. 다음 버전에서 정정해야 한다.

한 PR에 changeset 파일이 여러 개 있어도 되나

된다. 서로 다른 CHANGELOG 항목으로 남기고 싶은 변경이 있다면 여러 개를 만들 수 있다. 같은 패키지에 여러 changeset이 있으면 가장 높은 bump 수준이 적용된다.

squash merge를 써도 되나

된다. Changesets는 main 브랜치에 changeset 파일이 있는지만 본다. merge 방식은 중요하지 않다.

Version Packages PR을 닫았더니 다시 열렸다

main에 처리되지 않은 changeset 파일이 남아 있으면 봇은 다시 PR을 만든다. 릴리즈를 미루고 싶다면 PR을 닫기보다 열어두거나 draft로 두는 편이 낫다.

changeset version과 changeset publish의 차이

• changeset version: 버전 bump와 CHANGELOG 갱신
• changeset publish: npm publish 실행

CI에서는 먼저 changeset version으로 Version Packages PR을 만들고, 그 PR이 머지된 뒤 changeset publish를 실행한다.

릴리즈 검증

fluo에서는 publish 전에 pnpm verify:release-readiness를 실행한다. 이 검증은 대략 다음을 확인한다.

• 빌드, 타입체크, 전체 테스트 통과
• CLI E2E 검증
• 문서의 패키지 목록과 실제 패키지 폴더 일치 여부
• 공개 패키지가 내부 패키지를 workspace:^로 참조하는지
• LICENSE 파일 존재 여부
• CHANGELOG 구조 적합성

로컬에서도 실행할 수 있다.

pnpm verify:release-readiness
pnpm generate:release-readiness-drafts

새 패키지를 추가했거나 패키지 구조를 바꿨다면 CI 전에 한 번 돌려보는 게 좋다.

명령어 요약

일상적으로 직접 쓰는 명령은 많지 않다.

# PR 작업 중 changeset 파일 만들기
pnpm changeset

# 대기 중인 changeset과 예정 bump 확인
pnpm changeset status

# beta pre-release 진입
pnpm changeset pre enter beta

# pre-release 탈출
pnpm changeset pre exit

# 릴리즈 준비 검증
pnpm verify:release-readiness

version-packages와 release는 보통 CI가 실행한다.

{
  "scripts": {
    "version-packages": "changeset version",
    "release": "pnpm build && changeset publish"
  }
}

정리

Changesets 워크플로우를 한 줄로 줄이면 이렇다.

변경할 때 선언하고, 머지할 때 버전을 올리고, CI가 배포한다.

fluo처럼 패키지가 39개까지 늘어나면 수동 릴리즈는 금방 한계에 부딪힌다. GitHub Actions로 명령 실행을 자동화해도, 어떤 패키지를 올릴지와 어떤 내용을 CHANGELOG에 남길지는 여전히 사람이 기억해야 한다.

Changesets는 그 판단을 PR 시점으로 옮긴다. 코드를 작성한 사람이 변경 영향과 semver 수준을 기록하고, 리뷰어는 코드와 함께 그 판단을 검토한다. 이후 버전 bump, 내부 의존성 전파, CHANGELOG 생성, npm publish, GitHub Release는 자동화된다.

처음에는 changeset 파일 하나 더 만드는 일이 번거롭게 느껴질 수 있다. 하지만 몇 번 릴리즈를 돌려보면 이 파일이 단순한 절차가 아니라 릴리즈 품질을 지키는 장치라는 걸 알게 된다. 사용자가 CHANGELOG를 읽고 업그레이드 여부를 판단할 수 있다면, Changesets는 제 역할을 하고 있는 것이다.