GitHub Issues 작성 가이드

GitHub Issues는 프로젝트의 작업을 체계적으로 관리하고 협업 효율을 높여주는 핵심 도구이다.
이 문서는 명확하고 재사용 가능한 이슈 템플릿을 작성하는 방법을 정리한 가이드이다.
계획대로 진행되지 않는 것이 개발이기 때문에 자세한 내용은 PR에 작성하고
이슈에서는 간략하게 적는 것이 좋다.

1. 이슈 작성 목적

GitHub Issues는 다음과 같은 상황에서 사용된다.

새로운 기능(Feature) 구현
버그(Bug) 리포트 및 해결
리팩토링, 테스트 코드, 문서화 작업 요청
작업을 세분화하여 프로젝트 관리 효율 극대화
협업 시 작업 중복 방지 및 진행 상태 공유

2. 이슈 기본 구성 요소

✔ 1) 이슈 제목(Title)

간결하게 핵심을 담아쓰기
[Feature] WebSocket 메시지 읽음 처리
[Bug] JWT Refresh Token 검증 실패
[Refactor] MemberService 비밀번호 검증 로직 개선 등등

✔ 2) 라벨(Label)

이슈의 성격을 빠르게 파악하기 위해 라벨을 적용합니다.

✔ 3) 본문(Body)

이슈 설명은 아래 4가지를 기본으로 구성합니다.

(1) Summary — 이슈 개요

이 이슈가 무엇을 위한 것인지 한 문장으로 설명합니다.

WebSocket 기반 채팅에서 메시지 읽음 처리 기능을 구현한다.

(2) Detail — 상세 설명

현재 상태와 해결해야 할 목표 상태를 구체적으로 작성합니다.

현재 메시지를 읽어도 읽음 상태가 서버에 저장되지 않아 다른 사용자에게 반영되지 않는다.
채팅방별로 유저의 lastReadMessageId 값을 저장하고 이를 기반으로 읽음 처리를 구현해야 한다.

(3) Acceptance Criteria — 완료 조건

개발이 끝났음을 판단할 수 있는 체크리스트를 작성합니다.

- [ ] 사용자가 채팅방을 구독하면 마지막 메시지 ID를 전달한다.
- [ ] 서버는 lastReadMessageId 계산 후 DB 또는 캐시에 저장한다.
- [ ] 읽음 상태를 WebSocket 이벤트로 전달한다.
- [ ] 명세서(ws-api.md)에 읽음 처리 플로우가 추가된다.

(4) Reference — 참고 자료

관련 문서, ERD, API 명세, PR 링크 등을 포함하면 큰 도움이 됩니다.

- ERD: /docs/chat_erd.png
- API 명세서: /docs/websocket-api.md
- 관련 PR: #23

3. 이슈 세분화 기준

큰 기능 단위는 반드시 작은 이슈들로 나누는 것이 좋습니다.
기능을 잘게 쪼개면 아래 장점이 있습니다:

PR 크기가 작아져 리뷰가 쉬움
트러블슈팅이 쉬워짐
작업 책임 범위가 명확해짐
일정 관리 가능 (칸반 보드에서 트래킹하기 쉬움)

예: 채팅 서비스 기능 세분화

기능	나눌 수 있는 세부 이슈
WebSocket 연결	WebSocket 설정, 핸드셰이크 인증 처리
채팅방 구독	구독 이벤트 처리, 유저-방 매핑 구조
메시지 전송	DTO 정의, 메시지 저장, 메시지 브로드캐스트
메시지 읽음 처리	lastReadMessageId 계산, 저장 로직, 읽음 이벤트 송신
채팅방 종료	세션 종료 처리, 사용자 상태 업데이트

오정빈

이전 포스트