여러 언어가 섞인 모노레포에서 Changesets로 버전 관리하기

모노레포의 골치 아픈 문제, 버전 관리

모노레포(monorepo)라는 개념이 이제 꽤 익숙하시죠. 여러 프로젝트를 하나의 저장소에 모아놓고 관리하는 방식인데요, Google이나 Meta 같은 회사들이 오랫동안 써온 구조이고, 요즘은 스타트업들도 많이 채택하고 있어요. 그런데 모노레포에서 가장 어려운 것 중 하나가 바로 버전 관리와 배포거든요.

특히 한 저장소 안에 Node.js 패키지도 있고, Python 라이브러리도 있고, Rust 크레이트도 있는 "다국어(polyglot) 모노레포"라면 문제는 더 복잡해져요. 어떤 패키지의 어떤 버전을 언제 릴리스할지, 변경사항 기록은 어떻게 남길지, 누가 결정할지 일일이 합의해야 하니까요. Luke Hsiao라는 개발자가 이 문제를 Changesets라는 도구로 깔끔하게 풀어낸 경험을 공유했는데, 참고할 만한 내용이 많습니다.

Changesets가 뭐냐면

Changesets는 원래 JavaScript 생태계에서 여러 npm 패키지의 버전을 조율해서 릴리스하기 위해 만들어진 도구예요. 개발자가 PR을 올릴 때 .changeset/ 디렉토리에 작은 마크다운 파일을 하나 추가해요. 거기에 "이 PR은 패키지 A의 minor 버전을 올려야 한다", "패키지 B의 patch를 올려야 한다" 같은 의도를 적어두는 거죠.

나중에 릴리스할 때가 되면 Changesets가 쌓여있는 파일들을 다 읽어서, 각 패키지에 어떤 버전을 매길지 자동으로 계산해요. 시맨틱 버저닝(Semantic Versioning) 규칙에 따라 major/minor/patch를 올리고, CHANGELOG.md도 자동 생성해주고, 실제 배포 명령까지 실행해주죠. Turborepo, Nx 같은 모노레포 도구들과도 잘 붙어있어요.

JavaScript 전용 도구를 다른 언어로 확장하기

문제는 Changesets가 기본적으로 package.json을 읽는다는 거예요. Python의 pyproject.toml이나 Rust의 Cargo.toml은 모르죠. 그래서 Luke Hsiao는 이걸 우회하는 패턴을 만들었어요.

핵심 아이디어는 각 비-JS 패키지 디렉토리에 가짜 package.json을 하나씩 두는 것이에요. 진짜 패키지 메타데이터가 아니라, Changesets가 인식할 수 있는 최소한의 이름과 버전만 적어둔 파일이죠. Changesets는 이 파일을 보고 버전을 관리하고, 릴리스 스크립트는 package.json에 써진 새 버전을 실제 pyproject.toml이나 Cargo.toml로 복사해주는 단계를 추가합니다.

이렇게 하면 개발자 입장에서는 언어와 상관없이 똑같은 워크플로우를 쓸 수 있어요. PR을 올릴 때 pnpm changeset을 실행하면 대화형으로 "어떤 패키지를 바꿨는지", "버전 bump 종류가 뭔지", "변경사항 설명이 뭔지" 물어보고, 그 결과가 마크다운으로 저장됩니다. 나중에 릴리스 PR이 머지되면 GitHub Actions가 각 언어 생태계에 맞게(npm publish, PyPI 업로드, cargo publish 등) 배포를 실행하는 거죠.

왜 이게 좋은 접근일까

기존에 많이 쓰던 방법은 각 언어마다 별도의 릴리스 도구를 두는 거였어요. JavaScript는 Changesets나 release-please, Python은 poetry-dynamic-versioning, Rust는 cargo-release 이런 식으로요. 문제는 기여자가 여러 언어 패키지를 동시에 수정하는 PR을 올렸을 때, 각 도구의 관례가 다르니까 따로따로 챙겨야 한다는 점이에요.

모든 언어를 Changesets 하나로 통일하면 문서화와 온보딩이 훨씬 간단해져요. "우리 리포에서는 모든 PR에 changeset 파일 하나 넣으세요"라는 한 문장이면 끝이거든요. 릴리스 담당자도 한 가지 도구만 이해하면 되고요.

비슷한 문제를 다른 방식으로 푸는 도구들도 있어요. release-please는 Google이 만든 도구인데 Conventional Commits을 기반으로 자동으로 버전을 산정해요. semantic-release는 커밋 메시지 규칙에 더 엄격하고요. Nx나 Turborepo는 자체 릴리스 기능을 내장하고 있어요. Changesets의 장점은 개발자가 명시적으로 "이 PR이 어떤 버전 변화를 의미하는지" 선언하게 한다는 점이에요. 자동 추론에 의존하지 않으니까 실수가 적거든요.

한국 개발자들에게 주는 힌트

한국에서도 모노레포 도입이 점점 늘어나고 있죠. 특히 프론트엔드 팀이 여러 서비스의 디자인 시스템이나 공용 유틸을 공유할 때, 또는 백엔드 팀이 여러 마이크로서비스를 한 저장소에 모을 때 자주 쓰여요. 이때 버전 관리 전략이 초반에 명확하지 않으면 6개월 뒤에 수습 못 할 만큼 혼란스러워질 수 있어요.

JS 위주 모노레포라면 Changesets를 그냥 도입하면 되고요, 만약 Python 서비스나 Rust 바이너리도 같이 들어있다면 오늘 소개한 가짜 package.json 패턴이 실용적인 해결책이에요. 사내 라이브러리라서 외부 배포가 없더라도, CHANGELOG 자동 생성과 시맨틱 버저닝을 강제하는 장치로도 유용하죠.

도입할 때 주의할 점은, 팀 전체에 "changeset 파일을 빼먹으면 CI가 실패한다"는 규칙을 강제해야 한다는 거예요. 안 그러면 몇 달 지나고 나면 변경사항이 누락된 릴리스가 나와서 신뢰가 깨지거든요. GitHub Actions에서 changeset status --since=main 같은 명령으로 검사할 수 있어요.

마무리

Changesets를 다국어 모노레포에 적용하는 이 패턴은 "도구를 바꾸지 말고, 얇은 어댑터 레이어를 덧붙여서 기존 도구를 활용하자" 는 실용적인 접근이에요. 완벽한 해결책은 아니지만, 여러 언어 생태계의 릴리스 도구를 하나로 통일한다는 관점에서는 충분히 시도해볼 가치가 있습니다.

여러분 팀은 모노레포를 쓴다면 어떤 방식으로 버전을 관리하시나요? 혹은 아직 폴리레포(polyrepo)가 더 나은 선택이라고 보시나요?