82 lines (58 loc) · 2.12 KB

Contributing Guide

이 문서는 daiso-mcp 저장소에 기여할 때 필요한 개발 환경, 작업 흐름, 품질 기준을 정리합니다.

사전 준비

Node.js: 20.x (.nvmrc 참고)
npm: Node 20에 포함된 버전 사용 권장

nvm use
npm ci
cp .env.example .env

.env에는 필요한 경우 ZYTE_API_KEY를 설정하세요.

개발 명령어

# 로컬 실행
npm run dev

# 포맷/린트/타입/테스트
npm run format:check
npm run lint
npm run typecheck
npm test

# 전체 검증
npm run check

브랜치 및 PR 규칙

기능/수정 단위로 브랜치를 분리하세요.
PR 본문은 .github/PULL_REQUEST_TEMPLATE.md를 따라 작성하세요.
병합 전 CI(Format/Lint/Typecheck/Test/Build)가 모두 통과해야 합니다.

커밋 메시지 규칙

접두사는 영어, 메시지는 한국어를 사용합니다.

feat: 새로운 기능
fix: 버그 수정
docs: 문서 수정
refactor: 리팩토링
test: 테스트
chore: 기타 설정/의존성 작업
ci: CI/CD 변경

예시:

feat: 올리브영 재고 조회 필터 옵션 추가
fix: 매장 검색 파라미터 검증 오류 수정
ci: PR 검증 워크플로우 추가

코드 작성 기준

TypeScript strict 모드를 유지합니다.
비동기/외부 API 호출에는 에러 처리를 포함합니다.
주석은 한국어로 작성합니다.
파일 길이는 450줄 내외를 권장합니다.

예외:

src/pages/openapi.ts는 OpenAPI 생성 로직 특성상 길어질 수 있습니다.
길이가 커지는 파일은 기능 단위 모듈 분리를 우선 검토하세요.

테스트 원칙

새 기능에는 테스트를 함께 추가하세요.
정상 케이스와 에러/엣지 케이스를 함께 검증하세요.
외부 API 의존 로직은 가능한 한 mock 기반으로 테스트하세요.

보안 주의사항

API 키, 토큰, 비밀번호, 개인정보를 커밋하지 마세요.
.env, .env.*, .dev.vars는 커밋 금지입니다.
보안 이슈는 공개 이슈가 아니라 SECURITY.md 절차를 따라 제보하세요.