Skip to content

Package Update Guide

Jump to bottom
yujeong-jeon edited this page Jun 29, 2026 · 2 revisions

대상 레포: NaverPayDev/pie · NaverPayDev/cli 네이버 파이낸셜 유저플랫폼 공통개발TF(@NaverPayDev/frontend)가 유지보수하는 공개 npm 패키지 모노레포입니다.

이 문서는 "코드 한 줄 고침 → npm에 새 버전이 나가기"까지의 전체 흐름을 처음 보는 사람이 따라올 수 있게 정리한 것입니다. 두 레포 모두 동일한 changesets + Turborepo + pnpm workspace 골격을 쓰고, 릴리스는 전부 GitHub Actions가 자동화합니다. 직접 npm publish 하는 일은 거의 없습니다.

0. 한눈에 보는 그림

 코드 수정 (브랜치)
      │
      ▼
 changeset 작성  ──(없으면 detect 봇이 PR에 자동 추가/안내)
      │
      ▼
 PR 생성 ──► CI(lint·test·build) + size-check + (pie) llms.txt 검증
      │
      ▼  리뷰 & approve & merge to main
      │
      ▼
 [봇] "🚀 version changed packages" PR 자동 생성
      │      (changeset-release/main 브랜치, 버전·CHANGELOG 반영)
      ▼  이 PR을 merge
      │
      ▼
 [봇] npm publish + GitHub Release 태그 생성  ✅ 배포 완료

핵심: 개발자는 "changeset 작성"과 "PR 머지" 두 가지만 하면 됩니다. 버전 계산·CHANGELOG·publish·release 태그는 전부 봇(npayfebot)이 처리합니다.

1. 사전 준비 (로컬 환경)

git clone git@github.com:NaverPayDev/pie.git   # 또는 cli.git
cd pie
pnpm install
pnpm run build      # Turborepo가 의존성 순서대로 빌드
pnpm run test

2. 가장 중요한 개념: changeset

changeset은 "이번 변경이 어떤 패키지를, 어떤 단위(major/minor/patch)로 올려야 하는지"를 기록하는 작은 마크다운 파일입니다. 이 파일이 있어야 버전이 올라가고 배포됩니다.

작성 방법

pnpm changeset

대화형으로 ① 바뀐 패키지 선택 → ② bump 단위 선택 → ③ 변경 요약 입력을 하면 .changeset/<random-name>.md가 생성됩니다.

---
'@naverpay/utils': minor
---

formatPrice 함수에 통화 옵션 추가

💡 pie 레포에는 /naverpay-changeset:changeset 스킬(naverpay-changeset)이 있어 변경된 패키지를 감지해 자동으로 changeset을 만들어 줍니다.

bump 단위 규칙

  • patch: 버그 수정, 내부 리팩터링
  • minor: 하위호환 되는 기능 추가
  • major: breaking change → 원칙적으로 지양 (아래 §6 참고)
  • 내부 의존성 변경은 자동으로 patch (updateInternalDependencies: patch)

changeset을 깜빡했다면?

detect changed packages 워크플로우가 PR에 붙어, 패키지가 바뀌었는데 changeset이 없으면 자동으로 추가하거나 안내해 줍니다.

  • 건너뛰고 싶으면 PR에 skip-detect-change 라벨을 붙입니다.
  • 문서/CI/설정만 고쳐서 버전을 올릴 필요가 없으면 changeset 없이 머지해도 됩니다(배포 안 됨).

3. 정식 릴리스(release) — 자동 2단계

main에 머지되는 순간부터는 사람이 손댈 게 없습니다. publish.yaml(pie) / release.yaml(cli)이 NaverPayDev/changeset-actions/publish@main을 통해 2단계로 동작합니다.

1단계 — 버전 PR 자동 생성

main에 쌓인 changeset이 있으면 봇이 changeset-release/main 브랜치에서 PR을 엽니다.

  • PR 제목: 🚀 version changed packages
  • 내용: changeset 소비 → 각 package.json 버전 bump → CHANGELOG.md 갱신 (커밋 메시지 📦 bump changed packages version)

→ 이 PR을 리뷰하고 머지하는 게 "배포 승인" 행위입니다.

2단계 — 실제 publish

버전 PR이 main에 머지되면(=다시 push) 봇이:

  1. pnpm run build
  2. pnpm release 실행
    • pie: changeset publish
    • cli: pnpm run build && changeset publish
  3. npm에 publish (access: public, OIDC trusted publishing)
  4. GitHub Release 태그 자동 생성 (create_github_release_tag: true)

봇 계정: npayfebot / npay.fe.bot@navercorp.com

즉, 머지를 두 번 합니다. ① 내 기능 PR 머지 → ② 봇이 만든 "version" PR 머지. ②를 머지해야 실제로 npm에 나갑니다.

4. npm 배포 인증: OIDC Trusted Publishing

이 레포들은 npm에 배포할 때 장기 토큰(NPM_TOKEN)을 쓰지 않습니다. 대신 npm의 OIDC trusted publishing을 사용합니다.

어떻게 동작하나

  1. GitHub Actions가 워크플로우 실행 시 단기(short-lived) OIDC 토큰을 발급받습니다. (그래서 워크플로우에 permissions: id-token: write가 필요합니다.)
  2. npm은 이 토큰의 출처(레포 + 워크플로우)가 패키지에 미리 등록된 trusted publisher와 일치하는지 검증합니다.
  3. 일치하면 npm이 그 순간에만 유효한 권한을 부여하고 publish가 진행됩니다. (이 기능을 지원하려면 최신 npm이 필요해, 워크플로우에서 npm install -g npm@...으로 업그레이드합니다.)

💡 장점: 유출·회전 관리가 필요한 npm 토큰을 시크릿으로 보관하지 않아도 되고, 배포 출처가 GitHub로 증명(provenance)됩니다.

신규 패키지의 첫 배포는 수동으로 해야 합니다

⚠️ OIDC trusted publishing은 npm에 이미 존재하는 패키지에만 설정할 수 있습니다. 새 패키지는 아직 npm에 없어 trusted publisher를 등록할 화면 자체가 없습니다.

따라서 새 패키지를 처음 배포할 때는 사람이 직접 배포해야 합니다.

  1. naverpay npm 조직에 포함된 npm 계정으로 로그인(npm login)합니다.
  2. 해당 패키지를 최초 1회 수동으로 publish 합니다. (예: pnpm --filter @naverpay/<pkg> publish --access public)
  3. 패키지가 npm에 생성되면, 그 패키지 설정에서 이 레포/워크플로우를 trusted publisher로 등록합니다.
  4. 이후부터는 위 자동 릴리스(§3)가 OIDC로 알아서 배포합니다.

즉, 첫 배포 1회만 수동이고, 그 다음부터는 전부 자동입니다. 기존 패키지를 수정하는 경우라면 신경 쓸 일이 없고, 새 패키지를 추가할 때만 위 절차가 필요합니다.

5. 미리 배포하기 — canary / rc (PR 코멘트 트리거)

정식 배포 전에 실제 npm에 설치해서 테스트하고 싶을 때 사용합니다. PR에 코멘트만 달면 됩니다.

코멘트 npm tag 버전 형식 용도
canary-publish 또는 /canary-publish canary {VERSION}-canary.{DATE}-{COMMITID7} 실험적/임시 검증
rc-publish 또는 /rc-publish rc {VERSION}-rc.{DATE}-{COMMITID7} 릴리스 후보 검증
  • 내부적으로 release:canary(= changeset publish --no-git-tag)를 PR 브랜치에서 실행합니다.
  • 설치: pnpm add @naverpay/<pkg>@canary (또는 @rc)
  • cli의 canary/rc, pie의 rc는 GitHub pre-release도 함께 생성합니다(create_release: true).

(pie) 수동 beta 프리릴리스 스크립트

prerelease.sh / select-prerelease.sh는 특정 패키지 하나를 골라 beta 태그로 수동 배포하는 보조 스크립트입니다.

./select-prerelease.sh   # 워크스페이스 선택 → npm version premajor --preid=beta → pnpm publish --tag beta

일상적으로 쓸 일은 거의 없고, 위 PR 코멘트 방식(canary/rc)을 우선 사용하세요.

6. 꼭 지켜야 할 규칙 / 함정

  • Breaking change 지양: 라이브러리 사용처에서 코드 수정이 필요한 변경은 최대한 피합니다. 불가피하면 사전 합의 + major bump + 명확한 마이그레이션 안내.
  • sideEffects: false: 모든 패키지가 선언 → 모듈 로드 시점 부수효과(side effect) 코드 추가 금지(트리셰이킹 깨짐).
  • catalog: 사용: React 등 peer dependency 버전은 pnpm-workspace.yaml의 catalog:로 통일. 버전 하드코딩 금지.
  • 자동 생성 파일 직접 수정 금지:
    • pie: packages/es-http-status-codes/src/status-code.ts, reason-phrase.ts
    • 공통: 봇이 만드는 CHANGELOG.md, version PR
  • base branch는 main (changeset config baseBranch: main).
  • cli의 fixed 그룹: @naverpay/commithelper-go + 플랫폼별 바이너리 4종(darwin-arm64/x64, linux-x64, win32-x64)은 항상 같은 버전으로 함께 배포됩니다(fixed 설정). 하나만 올릴 수 없습니다.

7. 레포별 차이 요약

항목 pie cli
성격 공통 라이브러리(utils, hooks, 컴포넌트) 개발 도구 CLI
주요 패키지 utils, vanilla-store, url-param-compressor, react-pdf, safe-html-react-parser, svg-manager, es-http-status-codes commit-helper, commithelper-go(+바이너리 4종), fmb, publint
릴리스 워크플로우 publish.yaml release.yaml
release 스크립트 changeset publish pnpm run build && changeset publish
특수 CI validate-llms, node-matrix(18/20/22), deploy-docs GoTest(Go 1.24)
detect 액션 detect-add@feature/fork-guide (fork guide on) detect-add@main
changeset fixed 그룹 없음 commithelper-go 계열 5종
커스텀 의존성 assemble-release-plan을 NaverPayDev fork로 override —

8. 자주 하는 작업 치트시트

# 새 기능/수정 작업
git switch -c feature/my-change
# ...코드 수정...
pnpm changeset                 # changeset 작성 (가장 중요!)
pnpm run build && pnpm test    # 로컬 검증
git push -u origin HEAD        # PR 생성

# PR에서 미리 배포해보고 싶을 때 → PR 코멘트로:
#   canary-publish   (또는 /canary-publish)
#   rc-publish       (또는 /rc-publish)

# 정식 배포: 내 PR 머지 → 봇의 "🚀 version changed packages" PR 머지

9. 막히면 / 긴급 상황

  • 버그·이슈: pie issues에 등록 후 @NaverPayDev/frontend 멘션
  • 긴급 핫픽스 배포 지원: 네이버 파이낸셜 공통개발 TF (nfn0000220@navercorp.com)
  • 행동 강령: CODE_OF_CONDUCT.md, 기여 가이드: CONTRIBUTING.md

Clone this wiki locally