Changeset이 말합니다. "패키지 변경되었다니까?"

changeset을 사용하다 보면, 분명 나는 한 개의 패키지만 수정했는데 pnpm changeset 명령어를 실행했을 때 수정하지 않은 다른 패키지들이 목록에 모두 나타나거나 자동으로 선택되는 경우가 있습니다.

오늘은 이 문제의 원인과 해결 방법에 대해 정리해 보겠습니다.

---

문제 상황

• 특정 브랜치(예: feature/bridge-fix)에서 작업을 완료한 후 pnpm changeset 실행.
• 나는 A 패키지만 수정했는데, changeset 목록에는 B, C, D 등 프로젝트 내 거의 모든 패키지가 포함됨.
• 실수로 그대로 진행할 경우, 의도치 않은 패키지들의 버전이 일괄적으로 올라가는 대참사가 발생할 수 있음.

원인 분석: baseBranch 설정

changeset은 현재 브랜치의 변경 사항을 감지하기 위해 기준이 되는 브랜치와 비교를 수행합니다. 이 기준은 .changeset/config.json 파일의 baseBranch 속성에 정의되어 있습니다.

보통 기본값은 main 또는 master로 되어 있습니다.

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "baseBranch": "main",
  ...
}

왜 문제가 발생하나요?

만약 여러분의 작업 흐름(Workflow)이 다음과 같다면 문제가 발생합니다.

1. main 브랜치에서 dev 브랜치가 파생됨.
2. dev 브랜치에 여러 피처 브랜치들이 머지됨 (이 과정에서 많은 패키지들의 코드가 수정됨).
3. 아직 dev 브랜치의 내용이 main으로 머지되지 않음.
4. 나는 dev 브랜치에서 새로운 feature/my-task 브랜치를 따서 작업함.
5. pnpm changeset 실행.

이때 changeset은 feature/my-task와 main을 비교합니다. dev에 이미 머지되어 있던 모든 변경 사항들이 main에는 없기 때문에, changeset 입장에서는 그 모든 것들이 "이번 작업에서 변경된 사항"으로 간주되는 것입니다.

해결 포인트

baseBranch 수정

만약 프로젝트의 주요 개발 및 머지 기준 브랜치가 dev라면, changeset 설정에서도 이를 명시해 주어야 합니다.

// .changeset/config.json 수정
{
  "baseBranch": "dev",
  ...
}

이렇게 수정하면 changeset이 현재 브랜치를 dev와 비교하게 되어, 내가 실제로 이번 태스크에서 수정한 파일이 포함된 패키지만 정확하게 필터링해 줍니다.

마치며

changeset은 버전 관리와 Changelog 생성을 자동화해 주는 아주 편리한 도구입니다. 하지만 잘못된 기준 설정은 의도치 않은 버전 펌핑(Version Bumping)을 유발할 수 있으므로, 프로젝트의 브랜치 전략에 맞춰 config.json을 꼭 확인해 보세요!