# 점메추 기여 가이드 (Contributing Guide) 🍱

[English Version](CONTRIBUTING.md)

`jeomaechu` 프로젝트에 활력을 불어넣어 주셔서 감사합니다! 이 프로젝트는 결정 장애를 겪는 현대인들에게 **고품질의 큐레이션된 식사 데이터**를 제공하는 것을 목표로 합니다. 여러분의 기여가 이 엔진을 더욱 강력하고 정확하게 만듭니다.

---

## 🎯 기여 원칙 (Our Philosophy)

1.  **하이퍼 리얼리즘**: 단순한 음식 이름이 아닌, 실제 우리가 일상에서 마주하는 "현실적인" 메뉴를 지향합니다. (예: "냉장고 파먹기 비빔밥", "스팸 구워서 따끈한 흰쌀밥")
2.  **정통성 (Authenticity)**: 글로벌 요리의 경우 어설픈 번역보다는 현지 발음이나 널리 통용되는 정확한 명칭을 사용합니다.
3.  **데이터의 질**: 단순히 개수를 늘리는 것보다, 사용자가 보았을 때 "아 이거다!" 싶은 설득력 있는 메뉴를 추가하는 것이 중요합니다.

---

## 📂 데이터 추가 규칙 (`jeomaechu/data.py`)

메뉴 데이터를 추가하거나 수정할 때는 다음 규정을 엄격히 준수해야 합니다.

### 1. 카테고리 분류 (`MENU_DATA`)
- 해당 요리의 문화권이나 성격에 맞는 정확한 카테고리에 리스트 형식으로 추가합니다.
- **중복 금지**: 이미 존재하는 메뉴인지 반드시 확인하세요.

### 2. 메뉴 명명 규칙
- **한국 요리**: 통상적인 명칭을 사용하되, 특징(예: 우삼겹 김치찌개)을 명확히 합니다.
- **글로벌 요리**: 원어 발음을 우선하되, 괄호로 보충 설명을 붙일 수 있습니다. (예: `챠슈덮밥`, `알리오올리오 파스타`)
- **이모지 사용**: 태그 로직에 활용되는 매운맛(`🌶️`) 등을 제외하고는 메뉴명 내에 과도한 이모지 사용은 자제합니다.

### 3. 태깅 시스템 (`TAGS`)
- 모든 메뉴는 키워드 기반으로 자동 태깅됩니다.
- 새로운 메뉴를 추가한 후, `TAGS` 사전의 각 항목(Spicy, Meat, Seafood 등)에 정의된 **키워드 리스트**에 해당 메뉴를 식별할 수 있는 핵심 단어가 포함되어 있는지 확인하세요.
- 필요하다면 해당 태그의 키워드 리스트에 새로운 키워드를 추가하여 탐지율을 높입니다.

---

## 💻 CLI 및 기능 기여 (`jeomaechu/cli.py`)

사용자 편의를 위한 새로운 기능이나 명령어를 추가할 때의 규칙입니다.

### 1. 단축 명령어 (Shorthand Commands)
- 새로운 한국어 단축 명령어를 추가할 때는 `Typer` 데코레이터를 사용합니다.
- 반드시 `help` 인자를 작성하여 사용자가 기능을 알 수 있게 합니다.
- 직접 로직을 구현하기보다 내부 헬퍼인 `_perform_pick()` 함수를 호출하여 일관된 출력 형식을 유지합니다.

### 2. 별칭 (Alias) 사용
- 자주 쓰일 수 있는 유의어는 `hidden=True` 옵션을 준 별칭 명령어로 등록하여 사용성을 높입니다. (예: `매운거` -> `매워`)

---

## 🚀 워크플로우 (Contribution Workflow)

1.  **Fork & Clone**: 리포지토리를 포크하고 로컬로 복제합니다.
2.  **Branch Creation**: 기능이나 데이터 추가를 위한 새 브랜치를 생성합니다 (`git checkout -b feature/new-menu`).
3.  **Implementation**: 규정을 준수하며 코드를 작성합니다.
4.  **Verification**: 터미널에서 `python3 -m jeomaechu.cli [명령어]`를 실행하여 정상 작동 여부를 확인합니다.
5.  **Pull Request**: 변경 사항을 커밋하고 PR을 보냅니다.
    - 커밋 메시지는 `feat:`, `fix:`, `docs:`, `data:` 등의 접두사를 사용하여 명확히 작성해 주세요.

---

## 🎨 스타일 가이드

- **Python**: PEP 8 스타일 가이드를 준수합니다. 모든 함수와 변수에는 가급적 타입 힌트를 명시합니다.
- **Markdown**: 문서의 가독성을 위해 일관된 헤더 계층과 표 형식을 사용합니다.
- **Bilingual**: 가능한 한 영문 문서(README, CONTRIBUTING)도 함께 업데이트하여 글로벌 접근성을 유지합니다.
- **설치 방식**: 새로운 의존성을 추가하거나 진입점을 변경할 때, 도커나 한 줄 명령어(Curl) 설치 방식이 깨지지 않는지 확인해주세요.

여러분의 아주 작은 기여 하나가 누군가의 오늘 점심을 행복하게 만들 수 있습니다. 즐거운 코드질/식사 되세요! 🍱
