기여하기

​

설정

git clone https://github.com/fim-ai/fim-one.git && cd fim-one
cp example.env .env                        # LLM_API_KEY is optional for contributors
uv sync --all-extras                       # Python dependencies
cd frontend && pnpm install && cd ..       # frontend dependencies
bash scripts/setup-hooks.sh                # pre-commit hooks (required)

uv run pytest tests/ -x -q                # tests
uv run mypy src/fim_one/                   # type check
uv run ruff check src/                     # lint
cd frontend && pnpm build && cd ..         # frontend build

​

타입 안전성

• 모든 공개 함수에 타입 힌트가 필요합니다.
• import-untyped (stub이 없는 타사 라이브러리)를 제외하고 # type: ignore를 사용하지 않습니다.
• forward reference를 위해 from __future__ import annotations를 사용합니다.
• CI를 통과시키기 위해 오류를 억제하지 말고 실제 타입을 수정합니다.

​

테스트

• 커밋하기 전에 모든 기존 테스트가 통과해야 합니다: uv run pytest tests/ -x -q.
• 테스트는 외부 서비스에 의존하면 안 됩니다 — unittest.mock / AsyncMock을 사용하여 데이터베이스, MCP 서버, HTTP 엔드포인트, LLM 호출을 모킹하세요.
• 커버리지와 함께 테스트를 실행하세요: uv run pytest --cov=fim_one.

​

코드 스타일

• 비동기 우선. I/O 바운드 작업에는 async def를 사용하세요. 이벤트 루프를 블로킹하지 않도록 동기 호출을 asyncio.to_thread()로 래핑하세요.
• 린팅을 위해 Ruff 사용. uv run ruff check src/ — 줄 길이는 100자입니다.
• 최소한의 __init__.py 내보내기. 공개 API만 다시 내보내고 내부 기호는 비공개로 유지하세요.
• 패키지 관리자. Python은 uv, 프론트엔드는 pnpm을 사용하세요. pip나 npm은 절대 사용하지 마세요.

​

Git 규칙

​

Pre-commit hook pipeline

​

i18n

• frontend/messages/en/{namespace}.json — UI 문자열
• docs/*.mdx (로케일 하위 디렉토리 아님) — 문서
• README.md — 프로젝트 readme

1. 로컬 pre-commit 훅 — .env에 LLM_API_KEY가 설정되어 있으면 실행됩니다. 번역은 푸시 전에 발생하므로 출력을 미리 볼 수 있습니다.
2. CI 폴백 — 로컬 훅에 키가 없어 건너뛴 경우, .github/workflows/i18n-sync.yml이 병합 후 master에서 번역하고 결과를 자동 커밋합니다.

​

데이터베이스 마이그레이션

• 모든 새로운 ORM 모델 또는 열에는 반드시 마이그레이션이 필요합니다 — metadata.create_all()에 의존하지 마세요.
• 모든 마이그레이션은 멱등성을 가져야 합니다 — fim_one.migrations.helpers의 헬퍼 함수(table_exists, table_has_column, index_exists)를 사용하세요.
• Boolean 기본값: server_default=sa.text("FALSE") / sa.text("TRUE"). 절대 "0" / "1"을 사용하지 마세요 — PostgreSQL은 Boolean 열에 대한 정수 리터럴을 거부합니다.
• SQLite는 ALTER COLUMN을 지원하지 않습니다 — 열 제약 조건 변경의 경우 op.batch_alter_table()을 사용하세요.
• 마이그레이션을 작성한 후 즉시 uv run alembic upgrade head를 실행하여 적용하세요.

​

빠른 참조

# Development
./start.sh dev                            # hot reload (Python + Next.js HMR)
./start.sh dev:api                        # API only, dev mode (hot reload)
./start.sh dev:ui                         # Frontend only, dev mode (HMR)
./start.sh api                            # FastAPI only (headless)

# Quality checks
uv run pytest tests/ -x -q               # tests (stop on first failure)
uv run pytest --cov=fim_one              # tests with coverage
uv run mypy src/fim_one/                  # type check
uv run ruff check src/                    # lint

# i18n
uv run scripts/translate.py --all         # force full retranslation

# Database
uv run alembic upgrade head               # apply migrations
uv run alembic revision -m "description"  # create new migration