GitHub에는 협업을 돕기 위한 다양한 기능들이 있으며, 그 중 하나가 바로 Issue 기능이다.
일반적으로 Issue는 ‘문제점’으로 번역되지만, 실제로는 단순한 버그 신고뿐만 아니라 기능 개발, 작업 요청, 개선 제안 등 개발과 관련된 다양한 항목을 관리하는 데 범용적으로 사용된다. 이러한 관리를 통해 프로젝트를 더욱 체계적으로 관리할 수 있다.
이번 글에서는 실제 개발 과정에서 Issue를 어떻게 효과적으로 활용할 수 있는지, 그리고 Issue를 보다 간편하게 생성할 수 있도록 도와주는 Issue 템플릿 기능에 대해 알아보고자 한다.
GitHub Issue란?
GitHub Issue는 GitHub 저장소(repository)에서 작업 항목을 추적하고 협업하기 위한 도구이다.
작업 항목이라고 한다면, 버그 리포트, 기능 요청, 작업 할당, 질문, 기록 등 전반적으로 모든 협업 과정에서 사용되는 단위를 나타낸다.
이를 나타내는 것뿐만 아니라 협업을 위한 도구로서의 기능 역시 제공하는데, 담당자(assignee) 설정, Pull Request와 연계하는 등 작업을 구조화하고 진행 상황을 추적하는 데에 중요한 역할을 한다.
그러나 우리는 효율적인 개발자가 아닌가. 하나의 Issue 사안마다 관련된 Issue를 생성하는 것은 시간적인 리소스가 너무 많이 소요될 것이다. 앞서 Issue를 여러 작업 항목으로 분리할 수 있다면, 이 작업 항목들에 대해 어느 정도 공통된 양식을 적용할 수 있지 않을까?
이를 위해 GitHub에서 제공하는 기능이 Issue 템플릿이다.
각 작업 항목별로, 혹은 자주 사용되는 양식을 템플릿화하여 Issue 생성 시간을 단축시킬 수 있다. 이 Issue 템플릿을 생성하는 방법에 대해 알아보고, 실제로 작업 중인 프로젝트에 생성해 보자.
Issue 템플릿 생성하기
Issue 템플릿은 Organization과 Repository 단위 모두에 적용할 수 있다.
온라인상에서 별도로 설정하는 것이 아니라 프로젝트 내의 파일 형태로 존재하기 때문에, GitHub는 해당 파일을 감지하여 이슈 작성 화면에 템플릿을 자동으로 노출하게 된다.
이를 간편하게 생성하는 방법에 대해 알아보자.
나의 경우 현재 NEXT.JS를 이용한 개발 업무를 배정받았기에, 막 생성한 레포지토리 및 프로젝트에 템플릿을 생성해 보았다.
먼저 레포지토리의 Settings에 들어간다.
아래 'Set up templates' 버튼을 클릭한다. 앞서 언급한 템플릿 파일을 간편하게 생성해주는 도구라고 생각하면 된다.
들어가면 위와 같은 화면일 텐데 버그 리포트를 위한 템플릿, 기능 개발을 위한 템플릿, 혹은 유저가 원하는 대로 커스텀 가능한 템플릿 형태가 존재한다.
주로 Issue 중 대다수는 기능 개발 혹은 버그 리포트를 위해 많이 쓰이므로, 이를 위한 템플릿들을 만들고자 한다.
먼저 기능 개발 템플릿을 만들어 보자.
사실 셋 중 무엇을 선택해도 기본 템플릿 형태만을 제공해줄 뿐 결국 우리가 내용을 수정할 수 있으므로, 셋 중 아무거나 선택해도 무방하다.
나는 위와 같이 기능 개발 템플릿을 구성하였다. 각각의 섹션에 대해 설명하자면
- Template name : 템플릿의 이름. 이슈 생성 시 템플릿을 고르는 옵션으로 해당 이름이 보여진다.
- About : 위 템플릿의 이름을 보여줄 때, 간단하게 템플릿을 설명하는 섹션이다.
- Template content : 실제 이슈 작성 시의 본문 템플릿이다. 마크다운을 지원한다.
- Issue default title : 실제 이슈 작성 시 제목을 작성할 때, 기본 값(placeholder)를 나타낸다.
- Assignees : 실제 이슈 작성 시 기본으로 담당자를 배정하고 싶을 때 사용한다.
- Labels: 실제 이슈 작성 시 기본으로 라벨을 붙이고 싶을 때 사용한다. 버그/기능 등등 많은 라벨이 존재한다.
Optional additional items 부분은 작성하지 않아도 되지만 현재 프로젝트의 경우 개인 레포지토리에서 작업이 되고, 또한 기능 개발 템플릿이기에 고정적으로 담당자 및 라벨 값을 부여해 주었다.
## 🛩️ Description
작업에 대한 간단한 설명을 작성합니다.
## ☑️ Todos
- [ ] TODO
- [ ] TODO
버그 리포트 템플릿 역시 유사하게 구성해주었다.
## 🐞 Bug Description
버그에 대한 간단한 설명을 작성해주세요.
ex) Android 환경에서 어플리케이션 접속 후 로그인 시 에러가 발생합니다.
## ✅ Expected Behavior
기대했던 동작을 간단히 설명해주세요.
## 🔁 Reproduce
버그를 재현하기 위한 과정을 작성해주세요.
1. ...
2. ...
## 🖼️ Screenshots
가능하다면 문제를 보여주는 스크린샷을 첨부해주세요.
## 🧩 Additional Context
기타 참고할 만한 정보나 로그 등이 있다면 작성해주세요.
모든 템플릿 생성이 완료되면, 우측 'commit changes' 버튼을 눌러 주자.
성공적으로 Issue 템플릿이 생성되었다! 이제 Issue를 직접 생성해 보자.
Issue 생성 시 이와 같이, 앞서 생성한 템플릿들이 뜨게 되고
템플릿 선택 시, 위와 같이 사전 정의된 템플릿이 보여지게 된다.
새로 만든 프로젝트에서는, 첫 번째로 기본적인 레이아웃 구성을 완료하기 위해 이와 같이 Issue를 수정해 주었다.
이처럼 Issue 템플릿을 활용하면, 반복적인 작업 없이도 간편하고 일관된 방식으로 Issue를 생성할 수 있다.
또한, Issue와 연계하여 적절한 브랜치 전략을 함께 적용하면, 작업 단위에 따라 브랜치를 생성하고 정리하는 과정을 체계적으로 관리할 수 있어 프로젝트의 유지보수성과 협업 효율성을 크게 높일 수 있다.
자주 사용되는 브랜치 전략은 대표적으로 Git Flow, GitHub Flow가 있는데, 조만간 이에 대한 개념 및 실전 적용 방법에 대해서도 포스팅해 보겠다!