For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/updating-the-kit.md (or send Accept: text/markdown).
키트가 개선되면 복사본 업데이트하기
소스 저장소의 개선 사항을 복사본으로 가져오기 — 시작점을 기록하고, 새 리비전을 가져오고, 브랜치에서 머지하고, 배포 전에 검증합니다.
1. 시작점 기록하기
업데이트를 붙여넣기가 아니라 작은 프로젝트로 다루세요: 가지고 있는 키트 리비전과 더 새로운 것을 비교하고, 변경 사항을 가져오고, 배포 전에 브랜치에서 테스트합니다. 프로젝트가 키트 저장소의 포크 — GitHub이 소스와 연결된 채로 유지하는 복사본 — 이든 자기 앱에 복사한 코드든 이 방법은 같습니다.
다른 무엇보다 먼저 프로젝트에 세 가지를 적은 메모를 남기세요: 시작한 키트 커밋 — SHA, Git이 정확한 버전 하나를 식별하는 짧은 코드 — 받은 저장소(supastack-web, supastack-mobile, supastack-desktop 또는 All Platforms 모노레포), 그리고 이미 직접 해 둔 변경 사항.
키트 저장소들과 모노레포는 이력이 다르므로 한쪽의 브랜치를 다른 쪽의 포크에 절대 머지하지 마세요. 시작 SHA를 기록한 적이 없다면 포크에서는 git merge-base로 가장 가까운 공유 버전을 찾거나, 선택적 도입에서는 마지막으로 복사한 파일과 테스트를 식별하세요 — 정확한 기준이 불확실할 때는 더 넓은 diff를 검토하세요.
2. 새 리비전 가져와서 머지하기
아래 명령을 프로젝트 폴더 안의 터미널에서 실행하세요. 작업은 저장하고 커밋된 상태여야 합니다 — 깨끗한 작업 트리, 그래야 절반만 된 것이 머지에 섞이지 않습니다. 꺾쇠괄호 안의 단어는 바꿔 쓸 템플릿입니다: 전체 <thing> 대신 자기 값을 넣으세요. 표시된 GitHub 주소는 자리 표시자입니다. 포크한 저장소의 주소를 사용하세요.
각 줄이 하는 일: git remote add는 복사본에 kit-upstream이라는 두 번째 주소 — 키트 저장소 — 를 가르치고, git fetch는 파일을 건드리지 않고 최신 상태를 다운로드합니다. git switch -c는 별도의 업그레이드 브랜치를 만들어 리뷰하는 동안 메인 브랜치를 그대로 둡니다. git log는 받을 커밋을 나열하고 git diff --stat은 어떤 파일이 바뀌었는지 요약합니다. 커밋 제목만이 아니라 사용하는 모듈의 전체 diff를 읽으세요. git merge는 새 코드를 업그레이드 브랜치로 가져옵니다.
Git이 kit-upstream 리모트가 이미 있다고 하면 remote add 줄을 건너뛰고 git fetch로 계속하세요. <previous-kit-sha>는 1단계에서 기록한 시작 SHA입니다.
# Upstream is the platform repository you forked — substitute its real URL
# (supastack-web shown; use supastack-mobile or supastack-desktop as fits).
git remote add kit-upstream https://github.com/<org>/supastack-web.git
git fetch kit-upstream
git switch -c upgrade/kit-update
git log --oneline <previous-kit-sha>..kit-upstream/main
git diff --stat <previous-kit-sha>..kit-upstream/main
git merge kit-upstream/main3. 작업을 잃지 않고 충돌 해결하기
충돌은 양쪽이 같은 줄을 바꿨다는 뜻입니다: 키트가 앞으로 나아갔고 같은 곳을 커스터마이즈했습니다. Git은 머지를 멈추고 파일을 표시합니다 — 손상을 보고하는 것이 아니라 선택을 요청하는 것입니다.
표시된 각 파일을 편집기에서 열고 줄마다 결정하세요: 제품 고유의 텍스트, 이름, 설정은 유지하고 키트의 수정과 구조적 변경은 가져옵니다. 커스터마이즈한 파일을 키트의 새 버전 전체로 바꿔 충돌을 해결하지 마세요 — 작업이 지워집니다. 업그레이드 브랜치 안에서 해결하고 계속하기 전에 해결된 각 영역의 테스트를 실행하세요.
머지가 잘못되면 git merge --abort가 브랜치를 머지 전 상태로 되돌립니다. 이 플로의 어떤 것도 업그레이드 브랜치를 직접 머지하기 전까지 메인 브랜치나 배포를 바꾸지 않습니다.
4. 올바른 순서로 데이터 업데이트와 배포
새 키트 리비전은 데이터베이스를 바꿀 수 있습니다. packages/db/drizzle/ — 마이그레이션 폴더 — 의 새 파일을 읽고 마이그레이션 적용 전에 프로덕션 데이터를 백업하세요. 먼저 일회용 복사본에서 테스트하세요. 필요한 코드보다 호환되는 스키마 변경을 먼저 배포하세요: 마이그레이션이 데이터를 제거하거나 재구성하면 앱 코드만 롤백해서는 옛 스키마를 복원할 수 없습니다.
새 .env.example을 자기 설정과 비교하고 호스팅 대시보드에 새로 필요한 값을 추가하세요. .env 파일은 시크릿을 담고 Git에 절대 커밋되지 않습니다 — 각 머신과 배포에서 손으로 다시 만들며, NEXT_PUBLIC_와 EXPO_PUBLIC_ 값에는 넣지 않습니다.
배포 전에 키트 자체의 검증 게이트를 실행하세요. All Platforms 모노레포에서 corepack pnpm check:local은 유료 자격 증명 없이 lint, typecheck, 단위 테스트, 형식 검사를 실행합니다. corepack pnpm verify:local은 프로덕션 빌드와 브라우저 테스트 스위트를 추가합니다. 단일 표면 포크에서는 그 저장소 자체의 테스트와 빌드 명령을 실행하세요. 그다음 스테이징 스모크 패스를 하세요: 로그인하고, 두 번째 워크스페이스를 시도하고, 제품의 주요 사용자 여정을 실행하세요.
모두 통과하면 수용한 대상 SHA와 해결한 충돌을 적어 두세요 — 그 메모가 다음 업데이트의 시작 기준입니다.
corepack pnpm check:local
# fuller gate: adds the production build and browser suites
corepack pnpm verify:local5. 포크 대신 일부만 복사했다면
선택적 도입 — 키트 모듈을 기존 앱에 복사 — 은 키트와 Git 이력을 공유하지 않으므로 git merge가 도움이 되지 않습니다. 대신 옛 소스 SHA와 대상 소스 SHA를 비교하고, 도입한 부분에 닿는 변경만 옮기세요.
모듈의 공개 타입, 영속화 스키마와 마이그레이션, 서버 호출자, 구성, 테스트, 문서를 하나의 단위로 검토하세요 — 패키지 안의 변경은 다른 곳의 맞춤형 라우트나 환경 변경을 요구할 수 있고, 헬퍼 하나만 복사하면 나머지가 오래된 계약에 남습니다. 짧은 적응 메모 — 어떤 키트 파일을 가져왔고, 무엇을 건너뛰고, 무엇을 바꿨는지 — 를 남기면 다음 업데이트가 선택을 재생할 수 있습니다.
업데이트가 실행 중인 복사본의 무언가를 깨면 자기 변경을 되돌리기 전에 문제 해결 가이드를 먼저 따라가세요.