Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
58 lines (40 loc) · 2.95 KB

CONTRIBUTING.md

File metadata and controls

58 lines (40 loc) · 2.95 KB
Raw

기여 가이드

Arachne(아라크네)에 관심 가져주셔서 감사합니다. 작은 수정도 환영합니다.

개발 환경 (uv 전용 — OS 무관·재현)

git clone https://github.com/TaewonyNet/ArachneControl
cd ArachneControl

# uv 설치(없으면)
curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync                              # 의존성(개발 포함)
uv run playwright install chromium   # E2E용 헤드리스 브라우저(최초 1회)

운영·테스트 명령의 단일 출처는 docs/95_MANUAL.md 입니다.

uv run python scripts/verify.py      # ★ 완료 게이트(이 한 줄 exit 0 = DoD)
uv run pytest -q                     # 테스트(라이브 제외)
uv run ruff check src tests          # 린트
uv run mypy src                      # 타입
bun test src/arachne/client/ts       # 클라 JS 단위테스트(loader.ts 수정 시)

시스템 python/pip/pytest 직접 호출 금지(버전 드리프트). 항상 uv run ….

변경 흐름

  1. 이슈로 먼저 논의(버그/기능). 사소한 수정은 바로 PR.
  2. main에서 브랜치 분기: feat/..., fix/..., docs/....
  3. 커밋은 Conventional Commits(feat:·fix:·docs:·test:) 권장. 본문은 한국어/영어 모두 좋습니다.
  4. PR 전 로컬에서 uv run python scripts/verify.py exit 0 확인(pytest·ruff·mypy·bun·게이트 일괄).
  5. PR을 열면 CI(테스트·린트·시크릿 스캔)가 자동 실행됩니다.

게이트 원칙 (거짓-green 차단)

완료 판정은 오직 scripts/verify.py exit 0으로만 합니다. 게이트는 모듈 실재·Golden Test 라벨 추적성·강한 단언·보안 사실검사(인증/CORS/HMAC/MCP)·생성물 신선도를 AST로 검사합니다. 새 기능에는 Golden Test(GT-* 라벨)를 동반해 주세요.

버전 규약

유의적 버전(SemVer) MAJOR.MINOR.PATCH. 단일 진실원은 루트 VERSION 파일.

  • MAJOR: 비호환 변경 · MINOR: 하위호환 기능 추가 · PATCH: 하위호환 버그 수정.

기여 시 주의

  • 시크릿·실데이터 금지: 관리 토큰, 사내 호스트/IP, 실제 수집 데이터, 개인정보를 커밋에 넣지 마세요. CI 시크릿 스캔이 1차로 막지만 책임은 작성자에게 있습니다.
  • 실타겟 수집은 게이트 밖: 실 공개 사이트 수집은 @pytest.mark.live(수동 승인 트리거)로만. robots/ToS 준수 책임은 운영자(docs/specs/08_security_legal.md).
  • 테스트는 합성 픽스처로 작성하세요(실데이터 골든은 저장소에 포함하지 않습니다).
  • loader.ts(클라 인터프리터)를 바꾸면 bash scripts/build_client.sh로 loader.v2.js를 재빌드해 커밋(빌드 신선도 게이트가 검사).

라이선스

기여한 코드는 프로젝트와 동일하게 MIT로 배포되는 데 동의하는 것으로 간주합니다.