Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (72 loc) · 5.82 KB

CONTRIBUTING.md

File metadata and controls

81 lines (72 loc) · 5.82 KB

기여 및 작업 규칙

이 문서는 이 저장소에서 브랜치, 이슈, PR, 리뷰를 다룰 때 기본으로 따르는 작업 규칙을 정리한 문서입니다.

브랜치 규칙

  • 작업 브랜치는 가능한 한 이슈를 먼저 만든 뒤 생성합니다.
  • 브랜치 이름은 타입/issue-{번호}/{작업폴더}-{짧은-설명} 형식을 기본으로 사용합니다.
  • 타입은 아래 중 하나를 우선 사용합니다.
    • feat: 기능 추가나 사용자 동작 변화가 있는 작업
    • bug: 버그 수정, 회귀 수정, 오동작 보정
    • docs: 문서 수정
    • chore: 설정, 정리, 운영성 작업
  • 작업폴더는 실제로 가장 많이 바뀌는 폴더 이름을 넣습니다.
    • 예: codex-dictation, experiments, tools, repo
  • 여러 폴더를 같이 건드려도 브랜치에는 대표 폴더 하나만 넣고, 공통 작업이면 repo를 사용합니다.
  • 브랜치 이름만 봐도 어떤 이슈인지, 어떤 성격의 작업인지, 주로 어디를 만지는 작업인지 바로 추적할 수 있어야 합니다.
  • 예시는 아래와 같습니다.
    • bug/issue-29/codex-dictation-path-sanitization
    • docs/issue-30/repo-branch-convention
    • feat/issue-31/codex-dictation-always-listen-improvement
    • chore/issue-32/tools-log-cleanup

이슈 제목 규칙

  • 이슈 제목은 작업 단계와 의도를 빠르게 읽을 수 있게 [분류] 제목 형식을 기본으로 사용합니다.
  • 우선 추천하는 분류는 아래와 같습니다.
    • [기획]: 구현 전에 방향 정리, 설계, 아이디어 검토가 필요한 건
    • [작업]: 바로 구현하거나 처리 가능한 일반 작업
    • [버그]: 사용자 관점 오동작, 회귀, 수정이 필요한 문제
    • [정리]: 문서, 규칙, 명명, 범위, 표현처럼 비교적 가벼운 정돈
    • [리팩토링]: 기능 변화 없이 내부 구조, 책임 분리, 중복 제거를 개선하는 건
    • [유지보수]: 안정화, 의존성 정리, 경고 제거, 테스트 보강, 운영성 개선
  • 이슈 제목 분류는 사람 중심 분류입니다.
    • 예: 지금 무엇을 논의하는지, 당장 구현할 건지, 먼저 설계할 건지 빠르게 구분
  • 브랜치와 PR의 feat, bug, docs, chore, refactor는 기술 중심 분류입니다.
    • 예: 실제 변경의 종류와 구현 성격을 코드 작업 흐름에서 구분
  • 즉, 이슈 제목과 브랜치/PR 타입은 서로 대체 관계가 아니라 역할이 다릅니다.
  • 예시는 아래와 같습니다.
    • 이슈: [기획] always-listen 자동 감도 튜닝
    • 이슈: [작업] always-listen 분할/끝음 회귀 테스트 추가
    • 이슈: [버그] 특정 앱에서 출력 직후 입력 컨텍스트 초기화
    • 이슈: [정리] 브랜치 이름 규칙 문서화
    • 이슈: [리팩토링] always-listen 처리 책임 분리
    • 이슈: [유지보수] 로그 마스킹 옵션과 공유용 출력 정비
    • 브랜치: feat/issue-40/codex-dictation-auto-tuning
    • 브랜치: bug/issue-41/codex-dictation-output-context-reset

자기 PR 셀프 리뷰 기록 규칙

  • GitHub에서는 PR 작성자가 자기 PR에 APPROVE 또는 REQUEST_CHANGES 리뷰를 직접 남길 수 없습니다.
  • 다만 COMMENTED 리뷰와 일반 PR 코멘트는 남길 수 있으므로, 자기 PR을 검토할 때는 기본적으로 COMMENTED 리뷰를 사용합니다.
  • 이때 리뷰 본문 첫 줄에 의도된 판정을 아래 형식으로 명시합니다.
    • [의도된 판정] APPROVE
    • [의도된 판정] REQUEST_CHANGES
  • 즉, GitHub의 실제 리뷰 상태는 COMMENTED로 남더라도, 본문 첫 줄을 통해 검토 의도를 명확히 기록합니다.
  • 통과 의도일 때는 테스트 결과, 확인 범위, 머지해도 되는 이유를 함께 적습니다.
  • 수정 필요 의도일 때는 핵심 문제, 회귀 위험, 필요한 수정 방향을 함께 적습니다.
  • 필요하면 별도의 일반 PR 코멘트로 부연 설명을 달 수 있지만, 판정 성격을 남기는 기본 기록은 COMMENTED 리뷰 본문에 남깁니다.
  • 예시는 아래와 같습니다.
    • [의도된 판정] APPROVE
    • 검토 결과 추가 이슈는 보이지 않으며, 현재 기준으로 머지 진행이 가능합니다.
    • [의도된 판정] REQUEST_CHANGES
    • unknown/general 타깃에서 기존 출력 모드 회귀 가능성이 있어 수정 후 다시 확인이 필요합니다.

리뷰 지적 PR 재처리 절차

  • 리뷰에서 사실상 REQUEST_CHANGES 성격으로 막힌 PR은 아래 순서로 다시 정리합니다.
    1. 대상 브랜치에 최신 main을 먼저 반영하고 충돌이 있으면 해결합니다.
    2. 기존 리뷰 코멘트에서 지적된 문제를 코드와 테스트 기준으로 먼저 해결합니다.
    3. 관련 테스트를 다시 실행해 수정 내용과 회귀 여부를 확인합니다.
    4. 가능하면 처음 구현한 사람과 분리된 검토자 또는 별도 작업 단위로 다시 리뷰합니다.
    5. 재리뷰 결과에 따라 COMMENTED 리뷰로 최종 판정을 기록합니다.
  • 최종 판정 기록은 반드시 셀프 리뷰 규칙을 따릅니다.
    • 통과면 첫 줄에 [의도된 판정] APPROVE
    • 미통과면 첫 줄에 [의도된 판정] REQUEST_CHANGES
  • 통과 판정일 때만 머지합니다.
  • 미통과 판정이면 머지하지 않고, 핵심 이슈와 다음 수정 방향을 리뷰 본문에 남긴 채 PR을 유지하거나 보류합니다.
  • 여러 PR이 동시에 막혀 있으면 가능한 한 PR별로 작업 공간과 검토 단위를 분리해 병렬로 처리합니다.
  • 충돌 해결만 끝난 상태에서는 바로 머지하지 않고, 원래 리뷰에서 걸린 내용이 실제로 해소됐는지까지 확인한 뒤 판단합니다.
  • 즉, 이 절차의 기준은 충돌 해결이 아니라 리뷰 지적 해소 + 재검증 완료입니다.