기여 워크플로

먼저 이슈를 여세요

버그라면 최소 재현 코드, 브라우저와 GPU, Mirage 버전을 포함하세요. 기능이라면 구현보다 사용 사례를 먼저 설명하세요 — 이미 있는 data-* 속성이 답인 경우가 많습니다.

`main`에서 브랜치를 따세요

git checkout main
git pull
git checkout -b fix/traveler-scissor-offset

접두사	용도
`feat/`	새 기능
`fix/`	버그 수정
`docs/`	문서만
`refactor/`	동작 변경 없음
`perf/`	성능 작업
`chore/`	툴링, CI, 의존성

코드를 작성하세요

주변 코드에 맞추세요. 코드베이스는 2칸 들여쓰기, 큰따옴표, 세미콜론을 쓰는 TypeScript입니다. 공개 API에는 명시적 타입을, 내부에는 추론을 허용합니다.

가능하면 변경을 한 패키지 안으로 좁히세요. 여러 패키지를 건드려야 한다면 PR 설명에 이유를 적어 주세요.

빌드를 확인하세요

pnpm -r build

CI가 Node 20에서 정확히 이걸 돌립니다. 어느 패키지든 타입 오류가 있으면 실패합니다.

⚠️

아직 테스트 스위트가 없습니다. 생기기 전까지는 apps/dev(pnpm dev)에서 수동으로 검증하고, 무엇을 확인했는지 — 테스트한 브라우저, 시나리오 — PR에 적어 주세요.

changeset을 추가하세요

배포되는 패키지를 바꿨다면 반드시 필요합니다.

pnpm changeset

영향받는 패키지를 고르고, 범프 수준을 정하고, 사용자 관점의 요약을 쓰세요 — 그대로 changelog에 실립니다.

범프	사용처
`patch`	버그 수정, 내부 리팩터링, 패키지 README 문서
`minor`	새 옵션, 새 속성, 새 export
`major`	제거, 이름 변경, 기본값 변경

apps/docs만 바꾼 경우 changeset이 필요 없습니다 — docs는 private이라 배포되지 않습니다.

커밋

Conventional Commits를 씁니다.

fix(core): correct scissor offset for nested travelers
feat(painter): support repeating-linear-gradient
docs(guides): add Korean translation for performance

풀 리퀘스트를 여세요

다음을 설명하세요.

무엇을 왜 바꿨는지
어떻게 검증했는지 (브라우저, 시나리오)
시각적 변경이라면 스크린샷이나 화면 녹화
파괴적 변경은 명시적으로

새 `data-*` 속성 추가하기

패턴이 일관되어 있습니다. 다섯 단계를 모두 따르세요.

packages/core/src/types/attributes.ts에 선언합니다.

export const ATTR_THING = {
  NAME: "data-mirage-thing",
  KEY: "mirageThing",
  VALUES: { ON: "on" },
} as const;

Extractor.ts에서 element.dataset[ATTR_THING.KEY]로 파싱하고, 잘못된 토큰에는 예외를 던지세요 — 마크업에서 조용히 실패하면 디버깅이 괴롭습니다.
types/common.ts의 SceneNode에 실어 나릅니다.
Renderer.reconcileNode 등 적절한 곳에서 소비합니다.
apps/docs/pages/reference/data-attributes.mdx와 apps/docs/pages/ko/reference/data-attributes.mdx에 문서화합니다 — 두 로케일 모두.

패키지 추가하기

mkdir -p packages/thing/src

비슷한 패키지에서 package.json, tsconfig.json, vite.config.ts를 복사하세요(dom-tracker가 가장 단순합니다). 요구사항:

이름은 @mirage-engine/thing
"type": "module", main / module / types는 dist를 가리킬 것
vite build를 실행하는 build 스크립트
내부 의존성은 "workspace:*"로 선언
three를 쓴다면 직접 의존성이 아니라 반드시 peerDependency

pnpm-workspace.yaml이 이미 packages/*를 글로빙하므로 별도 등록은 없습니다.

스타일 규칙

영역	규칙
파일명	클래스는 `PascalCase.ts`, 유틸은 `camelCase.ts`
오류	`[Mirage]` 또는 `[MirageEngine]` 접두사
상수	`types/`에 `SCREAMING_SNAKE`
공개 API	명시적 반환 타입
주석	무엇이 아니라 왜를 설명
한글 주석	괜찮습니다 — 코드베이스가 이미 혼용 중입니다

버그 리포트

다음을 포함하세요.

Mirage 버전과 three 버전
브라우저, OS, GPU (chrome://gpu가 도움이 됩니다)
넘긴 config 객체 전체
최소 HTML/CSS 재현 코드
콘솔 오류, WebGL 경고 포함

아키텍처 릴리스