이슈와 프로젝트 관리

2. 핵심 원리

2.1 좋은 이슈 작성 — 재현·기대·실제

좋은 버그 이슈는 세 가지를 담습니다. 재현 방법(순서대로 몇 단계), 기대한 동작, 실제로 벌어진 동작입니다. 이 구조가 없으면 담당자가 상황을 재현하지 못해 질문이 왕복하며 시간이 낭비됩니다.

제목은 증상을 한 줄로 요약하고, 본문에는 버전·운영체제 같은 환경 정보를 덧붙입니다. 스크린샷이나 로그도 재현에 큰 도움이 됩니다.

2.2 이슈 템플릿 파일

.github/ISSUE_TEMPLATE/ 폴더에 파일을 두면 "New issue" 버튼을 누를 때 양식을 고를 수 있습니다.

파일 맨 위 --- 사이 영역(front matter)에 name·about·labels 를 적으면 이슈를 만들 때 제목과 라벨이 미리 채워집니다.

2.3 config.yml 로 빈 이슈 막고 외부 링크 추가

blank_issues_enabled: false 로 두면 양식 없이 빈 이슈를 바로 만드는 길을 막습니다. contact_links 항목으로 "질문은 여기로" 같은 외부 링크(Discussions 등)를 안내합니다.

2.4 라벨(label)로 분류

라벨은 색과 이름을 자유롭게 정할 수 있지만, 너무 세분화하면 아무도 정확히 골라 쓰지 않습니다. 팀 규칙으로 10개 안팎을 유지합니다.

2.5 담당자(assignee) 지정

Assignees 필드에 사람을 지정하면 그 사람의 할 일 목록에 이슈가 나타나고 알림이 갑니다. 여러 명을 동시에 지정할 수 있어 페어 작업에도 씁니다. 담당자가 없는 이슈는 "누구 것도 아닌 일" 이 되어 방치되기 쉽습니다.

2.6 마일스톤(milestone)으로 묶기

마일스톤은 이슈와 PR 을 하나의 목표(버전·스프린트)로 묶는 그릇입니다. 마일스톤 화면은 닫힌 개수와 전체 개수로 진행률을 막대로 보여줍니다. "v1.2 에 남은 일" 을 확인할 때 이슈 목록을 마일스톤으로 필터링합니다.

2.7 브랜치 이름에 이슈 번호 넣기

fix/12-login-timeout 처럼 번호와 요약을 함께 넣으면 브랜치 이름만 보고도 어떤 이슈인지 압니다. 접두어(fix/·feat/·chore/)를 팀 규칙으로 통일해 브랜치 목록이 성격별로 정렬되게 합니다.

2.8 커밋 메시지에 이슈 번호 넣기

커밋 본문에 #12 를 적으면 GitHub 가 이슈 화면에 그 커밋 링크를 자동으로 남깁니다. 로컬에서도 git log --grep '#12' 로 같은 이슈를 건드린 커밋을 모두 찾을 수 있습니다.

2.9 이슈 닫기 키워드

PR 이나 커밋 본문에 아래 키워드를 쓰면 병합과 동시에 이슈가 자동으로 닫힙니다.

닫기 키워드는 보통 커밋 본문이나 PR 본문에 적습니다. 제목에도 인식되지만, 본문에 적는 습관을 들이면 나중에 커밋만 봐도 의도가 분명합니다.

2.10 프로젝트 보드(칸반)

이슈와 PR 을 Todo·In progress·Done 같은 컬럼으로 옮기며 진행 상태를 한눈에 봅니다.

Todo              In progress        Done
------------------------------------------------
#7 다크 모드       #20 널 체크        #12 로그인 타임아웃

이슈를 닫거나 PR 이 병합되면 카드가 자동으로 Done 컬럼으로 이동하도록 규칙(workflow)을 걸 수 있습니다.

2.11 릴리스 노트 만들기

git log --grep 으로 특정 이슈를 닫은 커밋만 모으고, git shortlog 로 두 태그 사이 커밋을 작성자별로 묶으면 릴리스 노트 초안이 됩니다. GitHub 화면의 "Generate release notes" 버튼도 같은 일을 자동으로 합니다.

2.12 Discussions 와 Wiki

질문성 글이 Issues 에 계속 쌓이면 실제 작업 목록과 섞여 소음이 됩니다. 질문은 Discussions 로, 사용법 문서는 Wiki 로 분리합니다.