기여 가이드
문서 규칙
- 공식 문서는
docs/하위에 작성 - 파일명은 lowercase kebab-case
- 스레드/PR 맥락은 공식 문서 본문에 넣지 않음
- 기술 근거 링크는 기술 문서에 배치
커밋 컨벤션
- 커밋 제목 형식:
type: description - 예시:
docs: refine fundamentals chat contractfeat: add runtime checkpoint recovery
- 강제 검사: pre-commit
commit-msg훅 (scripts/validate-commit-msg.sh)
PR 컨벤션
- PR 제목 형식:
type: description - PR 본문 필수 섹션:
## Summary## Checklist## Validation## Related
- 템플릿:
.github/pull_request_template.md - 강제 검사:
.github/workflows/pr-convention.yml
머지 게이트 체크 매트릭스 (v1)
v1 게이트 모드는strict-required core only 입니다.
리뷰어 머지 체크리스트:
ci / required-ci가 green 인가PR Convention / convention이 green 인가- 필수 리뷰 수가 충족됐는가
- 참고용 체크에서 미해결 보안 우려가 남아 있지 않은가
브랜치 보호 (main)
저장소 관리자는 다음 기준을 적용해야 합니다.- pull request 필수
- force-push 비활성화
- required checks:
ci / required-ciPR Convention / convention
- 최소 1명 승인 리뷰
- 새 커밋 푸시 시 기존 승인 해제
- merge 전에 required status checks 통과를 강제합니다.
- v1 에서는
codeql / analyze (javascript-typescript)를 required check 로 지정하지 않습니다. check,docs,secrets,gitleaks를 별도 required check 로 중복 지정하지 않습니다.- bypass 권한은 저장소 관리자에게만 부여합니다.
임시 우회 경로 (오탐/거짓 실패 전용)
필수 체크가 툴링이나 플랫폼 문제로 거짓 실패했다고 판단될 때만 사용합니다. 제품 위험이나 테스트 실패가 남아 있으면 우회하면 안 됩니다. 필수 조건:- 실패한 run URL 을 PR 대화에 남길 것
- 왜 거짓 실패라고 판단했는지 승인자가 기록할 것
- merge 전 후속 이슈 또는 incident 링크를 남길 것
- 저장소 관리자가 승인할 것
- 우회는 해당 PR 1건에만 적용할 것
- merge 직후 일반 required-check 강제를 복구할 것
- 원인이 아직 열려 있으면 연결한 후속 이슈에서 추적하고, 추가 우회가 필요하면 매번 새 관리자 리뷰를 받을 것
네이밍 예시
- ✅
runtime-architecture.md - ✅
access-control.md - ❌
RuntimeArchitecture.md - ❌
runtime_architecture.md