-
Notifications
You must be signed in to change notification settings - Fork 4
Package Update Guide
대상 레포:
NaverPayDev/pie·NaverPayDev/cli네이버 파이낸셜 유저플랫폼 공통개발TF(@NaverPayDev/frontend)가 유지보수하는 공개 npm 패키지 모노레포입니다.
이 문서는 "코드 한 줄 고침 → npm에 새 버전이 나가기"까지의 전체 흐름을 처음 보는 사람이 따라올 수 있게 정리한 것입니다. 두 레포 모두 동일한 changesets + Turborepo + pnpm workspace 골격을 쓰고, 릴리스는 전부 GitHub Actions가 자동화합니다. 직접 npm publish 하는 일은 거의 없습니다.
코드 수정 (브랜치)
│
▼
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)이 처리합니다.
git clone git@github.com:NaverPayDev/pie.git # 또는 cli.git
cd pie
pnpm install
pnpm run build # Turborepo가 의존성 순서대로 빌드
pnpm run testchangeset은 "이번 변경이 어떤 패키지를, 어떤 단위(major/minor/patch)로 올려야 하는지"를 기록하는 작은 마크다운 파일입니다. 이 파일이 있어야 버전이 올라가고 배포됩니다.
pnpm changeset대화형으로 ① 바뀐 패키지 선택 → ② bump 단위 선택 → ③ 변경 요약 입력을 하면 .changeset/<random-name>.md가 생성됩니다.
---
'@naverpay/utils': minor
---
formatPrice 함수에 통화 옵션 추가💡 pie 레포에는
/naverpay-changeset:changeset스킬(naverpay-changeset)이 있어 변경된 패키지를 감지해 자동으로 changeset을 만들어 줍니다.
- patch: 버그 수정, 내부 리팩터링
- minor: 하위호환 되는 기능 추가
- major: breaking change → 원칙적으로 지양 (아래 §6 참고)
- 내부 의존성 변경은 자동으로
patch(updateInternalDependencies: patch)
detect changed packages 워크플로우가 PR에 붙어, 패키지가 바뀌었는데 changeset이 없으면 자동으로 추가하거나 안내해 줍니다.
- 건너뛰고 싶으면 PR에
skip-detect-change라벨을 붙입니다. - 문서/CI/설정만 고쳐서 버전을 올릴 필요가 없으면 changeset 없이 머지해도 됩니다(배포 안 됨).
main에 머지되는 순간부터는 사람이 손댈 게 없습니다. publish.yaml(pie) / release.yaml(cli)이 NaverPayDev/changeset-actions/publish@main을 통해 2단계로 동작합니다.
main에 쌓인 changeset이 있으면 봇이 changeset-release/main 브랜치에서 PR을 엽니다.
- PR 제목:
🚀 version changed packages - 내용: changeset 소비 → 각
package.json버전 bump →CHANGELOG.md갱신 (커밋 메시지📦 bump changed packages version)
→ 이 PR을 리뷰하고 머지하는 게 "배포 승인" 행위입니다.
버전 PR이 main에 머지되면(=다시 push) 봇이:
pnpm run build-
pnpm release실행- pie:
changeset publish - cli:
pnpm run build && changeset publish
- pie:
- npm에 publish (
access: public, OIDC trusted publishing) -
GitHub Release 태그 자동 생성 (
create_github_release_tag: true)
봇 계정: npayfebot / npay.fe.bot@navercorp.com
즉, 머지를 두 번 합니다. ① 내 기능 PR 머지 → ② 봇이 만든 "version" PR 머지. ②를 머지해야 실제로 npm에 나갑니다.
이 레포들은 npm에 배포할 때 장기 토큰(NPM_TOKEN)을 쓰지 않습니다. 대신 npm의 OIDC trusted publishing을 사용합니다.
- GitHub Actions가 워크플로우 실행 시 단기(short-lived) OIDC 토큰을 발급받습니다. (그래서 워크플로우에
permissions: id-token: write가 필요합니다.) - npm은 이 토큰의 출처(레포 + 워크플로우)가 패키지에 미리 등록된 trusted publisher와 일치하는지 검증합니다.
- 일치하면 npm이 그 순간에만 유효한 권한을 부여하고 publish가 진행됩니다. (이 기능을 지원하려면 최신 npm이 필요해, 워크플로우에서
npm install -g npm@...으로 업그레이드합니다.)
💡 장점: 유출·회전 관리가 필요한 npm 토큰을 시크릿으로 보관하지 않아도 되고, 배포 출처가 GitHub로 증명(provenance)됩니다.
따라서 새 패키지를 처음 배포할 때는 사람이 직접 배포해야 합니다.
-
naverpaynpm 조직에 포함된 npm 계정으로 로그인(npm login)합니다. - 해당 패키지를 최초 1회 수동으로 publish 합니다. (예:
pnpm --filter @naverpay/<pkg> publish --access public) - 패키지가 npm에 생성되면, 그 패키지 설정에서 이 레포/워크플로우를 trusted publisher로 등록합니다.
- 이후부터는 위 자동 릴리스(§3)가 OIDC로 알아서 배포합니다.
즉, 첫 배포 1회만 수동이고, 그 다음부터는 전부 자동입니다. 기존 패키지를 수정하는 경우라면 신경 쓸 일이 없고, 새 패키지를 추가할 때만 위 절차가 필요합니다.
정식 배포 전에 실제 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).
prerelease.sh / select-prerelease.sh는 특정 패키지 하나를 골라 beta 태그로 수동 배포하는 보조 스크립트입니다.
./select-prerelease.sh # 워크스페이스 선택 → npm version premajor --preid=beta → pnpm publish --tag beta일상적으로 쓸 일은 거의 없고, 위 PR 코멘트 방식(canary/rc)을 우선 사용하세요.
- 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
- pie:
-
base branch는
main(changeset configbaseBranch: main). -
cli의 fixed 그룹:
@naverpay/commithelper-go+ 플랫폼별 바이너리 4종(darwin-arm64/x64, linux-x64, win32-x64)은 항상 같은 버전으로 함께 배포됩니다(fixed설정). 하나만 올릴 수 없습니다.
| 항목 | 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 |
— |
# 새 기능/수정 작업
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 머지- 버그·이슈: pie issues에 등록 후
@NaverPayDev/frontend멘션 - 긴급 핫픽스 배포 지원: 네이버 파이낸셜 공통개발 TF (nfn0000220@navercorp.com)
- 행동 강령:
CODE_OF_CONDUCT.md, 기여 가이드:CONTRIBUTING.md