이슈와 프로젝트

🎯 학습 목표

이 강을 마치면 다음을 할 수 있습니다.

• GitHub Issues로 버그, 기능 요청, 개선 사항을 체계적으로 등록·관리할 수 있습니다.
• 라벨, 마일스톤, 담당자를 활용해 이슈를 분류하고 추적할 수 있습니다.
• 커밋이나 PR에서 특별 키워드로 이슈를 자동으로 닫을 수 있습니다.
• GitHub Projects 보드로 팀 작업을 칸반 방식으로 시각적으로 관리할 수 있습니다.

📝 GitHub Issues — 작업 추적의 시작

이 섹션에서는 개발팀의 모든 작업 단위를 기록하고 추적하는 GitHub Issues의 개념과 기본 사용법을 살펴보겠습니다.

Issues는 GitHub 저장소에 내장된 작업 추적 시스템입니다. 버그 신고, 새 기능 제안, 개선 사항 제안, 질문 등 프로젝트 관련 모든 것을 이슈로 만들어 관리합니다. 이슈가 있으면 "무엇을 해야 하는지"를 팀 전체가 공유하고, 진행 상황을 투명하게 추적할 수 있습니다.

이슈를 만들면 자동으로 번호가 부여됩니다 (#1, #2, #3...). 이 번호는 저장소 전체에서 유일하며, 커밋 메시지나 PR에서 이슈를 참조할 때 사용합니다.

# 이슈 참조 (커밋 메시지나 PR 설명에서)
git commit -m "fix: 로그인 버튼 비활성화 오류 수정 (ref #42)"

# PR 머지 시 이슈 자동 닫기 키워드
# Closes #42, Fixes #42, Resolves #42 → PR이 main에 merge되면 #42 자동 닫힘

🏷️ 라벨 — 이슈 분류와 필터링

이 섹션에서는 이슈에 라벨을 붙여 종류와 우선순위를 시각적으로 표시하고 필터링하는 방법을 살펴보겠습니다.

라벨(Labels)은 이슈와 PR에 붙이는 색상 태그입니다. GitHub는 기본 라벨을 제공하고, 팀에서 커스텀 라벨을 추가할 수 있습니다.

기본 라벨	의미
bug	버그 또는 예상과 다른 동작
enhancement	새 기능 또는 기존 기능 개선
documentation	문서 추가 또는 개선
good first issue	처음 기여하기 좋은 이슈 (오픈소스에서 활용)
help wanted	추가 도움이 필요한 이슈
question	추가 정보나 답변이 필요한 경우
wontfix	의도적으로 수정하지 않을 이슈

팀 관행에 따라 추가로 자주 쓰이는 커스텀 라벨 예시입니다.

• priority: high, priority: medium, priority: low: 우선순위
• status: in-progress, status: blocked: 현재 상태
• type: backend, type: frontend, type: infra: 담당 영역

이슈 목록에서 라벨 필터를 사용하면 "현재 진행 중인 버그만" 또는 "백엔드 관련 이슈만" 같이 빠르게 원하는 이슈를 찾을 수 있습니다.

🎯 마일스톤 — 목표와 기한 관리

이 섹션에서는 여러 이슈를 묶어 하나의 릴리즈나 스프린트 목표로 관리하는 마일스톤을 살펴보겠습니다.

마일스톤(Milestone)은 여러 이슈를 하나의 목표(릴리즈 버전, 스프린트 등)로 묶는 그룹입니다. 마일스톤에 포함된 이슈 중 몇 %가 완료됐는지 진행 바로 표시됩니다.

마일스톤 사용 예시입니다.

• v1.0.0 릴리즈: 출시에 필요한 필수 기능 이슈들을 묶어 진행 상황을 한눈에 파악
• 2주 스프린트 2024-W03: 2주 단위로 처리할 이슈들을 묶어 팀 속도 측정
• 성능 개선 프로젝트: 특정 목적의 이슈들을 묶어 별도 관리

# 이슈와 PR에서 마일스톤 설정은 GitHub 웹에서:
# 이슈/PR 우측 사이드바 → Milestone → 선택
# 마일스톤 관리: Issues 탭 → Milestones → New milestone
#   - Title: v1.2.0
#   - Due date: 2024-02-29
#   - Description: 사용자 인증 시스템 완성 릴리즈

📋 이슈 작성 — 좋은 이슈의 조건

이 섹션에서는 리포터와 개발자 모두에게 유용한 좋은 이슈를 작성하는 방법을 살펴보겠습니다.

좋은 이슈는 문제를 빠르게 이해하고 재현하는 데 필요한 모든 정보를 담고 있습니다.

버그 이슈 작성 템플릿 예시입니다.

• 환경: 운영체제, 브라우저 버전, 앱 버전 등
• 재현 단계: 1. 로그인 페이지 접속 / 2. 구글 로그인 버튼 클릭 / 3. 콜백 후 에러 발생
• 예상 동작: 메인 페이지로 이동해야 함
• 실제 동작: 500 서버 에러 페이지 표시
• 스크린샷 또는 에러 로그: 직접 첨부

이슈 템플릿을 설정하면 이슈 생성 시 자동으로 양식이 채워집니다. 저장소 .github/ISSUE_TEMPLATE/ 폴더에 마크다운 파일을 만들면 됩니다.

📊 GitHub Projects — 칸반 보드로 시각적 관리

이 섹션에서는 이슈와 PR을 칸반 스타일로 시각화해 팀 진행 상황을 한눈에 파악하는 GitHub Projects를 살펴보겠습니다.

GitHub Projects는 이슈와 PR을 카드로 표시하는 칸반 보드입니다. 각 카드를 드래그 앤 드롭으로 열(column) 간 이동하며 상태를 시각적으로 관리합니다.

Projects는 저장소 탭에서 "Projects" → "New project"로 생성합니다. 보드 뷰 외에 테이블 뷰, 로드맵 뷰도 제공합니다.

일반적인 칸반 열 구성 예시입니다.

• Backlog: 아직 시작하지 않은 이슈 목록
• In Progress: 현재 작업 중인 이슈
• In Review: PR이 열려 있고 코드 리뷰 중
• Done: 완료되어 main에 merge된 이슈

# Projects 자동화 설정 (GitHub Actions 연동)
# Settings → Projects → Automation 탭에서:
# - 이슈가 열리면 자동으로 "Backlog"로 이동
# - PR이 열리면 "In Review"로 이동
# - PR이 머지되면 "Done"으로 이동
# → 수동으로 카드 이동할 필요 없이 자동 관리

Projects는 단일 저장소뿐 아니라 여러 저장소의 이슈를 하나의 보드에서 관리하는 Organization-level Project도 지원합니다. 팀에서 여러 저장소를 운영할 때 유용합니다.

🔗 이슈 → 커밋 → PR → 자동 닫기 연결

이 섹션에서는 이슈, 커밋, PR을 서로 연결해 작업의 전체 맥락을 GitHub에 기록하는 방법을 살펴보겠습니다.

GitHub에서 커밋 메시지와 PR 설명에 특정 키워드를 사용하면 이슈와 자동으로 연결됩니다.

# 커밋 메시지에서 이슈 참조 (이슈에 자동 링크됨)
git commit -m "fix: 결제 실패 시 에러 메시지 표시 (ref #87)"

# PR 설명에서 이슈 자동 닫기 키워드
# Closes #87   → PR이 main에 merge될 때 #87 자동 닫힘
# Fixes #87    → 동일
# Resolves #87 → 동일

# 여러 이슈 동시에 닫기
# Closes #87, Closes #91, Fixes #93

이 연결 덕분에 이슈 페이지에서 "이 이슈를 해결한 PR이 무엇인지", PR 페이지에서 "이 PR이 어떤 이슈를 해결하는지"를 바로 확인할 수 있습니다. 6개월 후에 "이 기능을 왜 만들었지?"를 알 수 있는 귀중한 히스토리입니다.

📝 핵심 요약

14강에서 배운 내용을 정리해 보겠습니다.

기능	역할	주요 활용
Issues	작업 추적	버그·기능·개선 등록
Labels	이슈 분류	종류·우선순위·영역 표시
Milestones	목표 묶음	릴리즈·스프린트 관리
Projects	시각적 관리	칸반 보드, 진행 상황 한눈에

자동 닫기 키워드: PR 설명에 Closes #번호 → PR merge 시 이슈 자동 닫힘

다음 강인 15강 — 되돌리기 전략에서는 커밋을 취소하거나 수정하는 다양한 방법을 배웁니다. git revert, git reset, git stash의 차이와 각각의 안전한 사용 기준을 이해하면 실수를 두려워하지 않고 자신 있게 개발할 수 있게 됩니다!