Github Issue 똑똑하게 사용하기
Github Issue는 Github에서 제공하는 편리한 기능이다. 레포지토리마다 Issue를 생성해서 관련된 문제사항이나 앞으로 작성해야 하는 작업 사항들을 적어 보관해 둘 수 있다. 대부분의 경우 버그리포트를 작성하거나 진행중/계획하고 있는 피처 개발 계획 등을 적어두는 방식으로 하는데, Github에서 제공하는 여러가지 부가기능들을 통해 정말 다양한 방식으로 활용할 수 있다.
Github Issue의 숨겨진 꿀기능 중 하나로 Issue에서 직접 Branch를 생성할 수 있는 기능이 있다! 이렇게 Branch를 생성하면 Issue와 Branch가 연결관계를 가지게 되서, Branch가 main에 머지되면 자동으로 Issue가 닫히는 등 소소한 편의기능을 누릴 수 있다(Branch 이름짓는 수고가 덜 든다는 더 소소한 장점도 있다). Branch 생성 기능은 아래와 같은 순서로 사용할 수 있다.
- Issue에 들어가서 좌측에 있는 create a branch 버튼을 누른다.
-
Branch를 생성할 Source 브랜치를 고르고, 브랜치명을 확인/수정한다.
-
Create Branch 버튼을 누르면 Branch 생성 완료!
Github는 Commit을 Issue와 연결짓는 기능도 제공한다. 아주 간단하게 Commit message에 #<Issue Number> 구문이 포함되면 remote에 올라 갈 때 자동으로 Issue에 해당 커밋을 참조하고 있다고 표시가 생겨난다.
이에 더해서 만약 Commit에 아래와 같은 키워드가 있는 경우 Issue를 자동으로 닫아줄 수도 있다!
close
closes
closed
fix
fixes
fixed
resolve
resolves
resolved
다만, Issue 닫기 기능은 해당 커밋이 main branch에 merge되었을 때만 동작한다. 또, 동시에 여러개의 Issue를 커밋 메시지에 언급하는 경우, 맨 앞의 하나만 연결되는 단점이 있다.
Github에서는 Issue Template을 만들어두고, 이를 Issue 생성시에 자동으로 반영하는 기능도 지원한다! 사용 방법은 아래와 같다.
- 레포지토리에
.github/ISSUE_TEMPLATES/디렉토리를 만들고, 내부에 마크다운 파일을 하나 생성한다.
---
name: (Old) Bug Report
about: Create a report to help us improve
title: 'fix: '
labels: ''
assignees: ''
---
## 버그 설명
## **버그 재현법**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
...
- 위와 같은 양식으로 마크다운 파일을 작성한다. 상단부 ---로 구분된 영역은 템플릿의 메타데이터를 지정하는 부분이며, 템플릿의 이름, 간단한 설명, 디폴트 제목, 자동으로 달릴 라벨과 담당자를 미리 지정해 둘 수 있다. 그 아래의 영역은 마크다운 양식으로 자동으로 들어가 있을 내용을 작성하면, 해당 템플릿으로 이슈를 생성했을 때, 자동으로 해당 내용들이 들어가 있는 것을 확인할 수 있다.
- 이제 해당 템플릿을 main branch에 push한 후, 레포지토리 Issue Tab에 가서 Create Branch를 누르면...
- 위와 같이 생성한 Issue Template이 메타데이터에 지정한 제목과 설명으로 나타나는 것을 확인할 수 있다.
- Create Issue로 Issue를 생성해보면, 아까 지정한 양식이 그대로 적용되어 있는 것을 확인할 수 있다!
Issue를 사용하다 보면, Issue간의 관계가 생기거나, Issue간 hierarchy가 있어 이를 통합적으로 관리하고 싶을 때가 있다. 이럴 때는 Github Issue의 Tasklist 기능을 활용하면 좋다.
↓
우선, Github 내의 대부분의 마크다운 문서에서는 #를 통해 Issue의 링크를 만들 수 있다. 이렇게만 생성하면 단순하게 링크이지만...
↓
위와 같이 Issue 링크 앞에 Github 마크다운의 Todo 양식을 적용시키면 Issue에 Tasklist가 적용된다. Tasklist가 적용되면, 연결된 Issue 항목이 닫힐 경우 자동으로 앞의 Todo 체크박스가 체크 상태가 되고, 전체 Tasklist의 진척도가 Issue에 표시되게 된다!
단, 전반적으로 상태 업데이트가 Issue의 변화 이벤트에 의해서 촉발되기 때문에, 별도로 Todo를 체크하거나, 이미 닫힌 Issue를 빈 Todo Syntax에 달아서 신규 생성하는 경우 자동으로 업데이트 되지 않는 등 일부 단점이 존재한다.
주의) 이 기능은 2022.11.27 기준 Github에서 제공하는 Beta 기능입니다.
앞서 배운 Issue Template을 사용하더라도, 때때로 그 효용성에 대해 의구심이 드는 경우가 많다.
실질적으로 Issue Template이 하는 역할은 Issue가 가질 수 있는 많은 항목들에 초기값을 설정하는 것일 뿐, Template 로드 후에는 얼마든지 사용자가 모든 항목을 수정할 수 있다. 또한, 특정 작성 양식을 예시문으로 적어보아야 시스템적인 제약은 전혀 걸려있지 않고, 해당 예시 양식들을 실제 작성할 때 결국 사용자가 일일히 지워야 하는 등, 단순한 Textarea 형태의 입력창은 그 한계가 굉장히 뚜렷한 편이다.
그리고 이런 단점들을 해결할 수 있는 솔루션이 바로 Github Issue Form이다. Issue Form은 Github에서 현재 베타 버전으로 제공하고 있는 기능으로, 기존에 마크다운 양식을 사용하던 Template 대신에 yml 형식으로 Issue Form을 사전에 정의한다. Issue Form으로 템플릿을 작성하고 사용하면, 기존과 달리 하나의 Textarea를 제공하는게 아니라, Form에 지정해 놓은대로 Input Field들을 나누어 제공한다! 기본적으로 각 Field마다 제목, 설명, 필수입력 설정, 입력 양식 제한(Input, Textarea, Dropdown, Checkbox)을 제공하며 Issue Template과 달리 사용자의 입력값과 템플릿의 양식이 별도관리 되므로 안내사항 등의 작성이 매우 편리해진다.
이랬던 이슈 템플릿이...
이렇게 변화할 수 있다!
템플릿을 폼 형태로 변경하는 것은 생각보다 매우 편리하다! 설명은 공식문서 여기에 잘 나와있고, Issue Form 자체의 문법에 대해서는 여기에 설명이 되어있다.
OaO 프로젝트에 Issue Form을 적용하면서 느낀 대표적인 장점들은 아래와 같은 것들이 있다.
- 입력 항목에 맞는 입력 형태 선택가능
→ 한줄짜리 입력, 텍스트상자, 체크박스, 드롭다운 선택 메뉴 등. 특히 드롭다운과 체크박스는 사용자가 텍스트 형태로 작성해야 하던 항목들에 선택지 형태로 입력을 제공할 수 있어서 매우 강력한 기능이다. - 입력 항목에 필수입력 조건 설정 가능
→ 이슈를 대충 작성하거나, 중요한 요소를 빼먹는 것을 방지할 수 있다! - 명확한 항목 분할로 인한 작성의 편리함
→ 마크다운으로 작성할 때에 비해 Input 필드 자체가 분리되어 있어, 각 항목이 직관적으로 잘 보이고, 작성이 편리하다 - 별도의 안내사항 전달 가능
→ 기본적으로 각 항목의 description은 입력과 별도로 이슈 생성시에 사용자에게만 제공되는 안내문이다. 그 외에도 markdown 속성 필드를 이용해 생성될 이슈 내용과 별개로 작성중인 사용자에게 전달하고 싶은 내용을 적어둘 수도 있다. - 비어있는 항목에 No Response 표시
→ 별거 아니지만 막상 표시가 있는 것과 없는 것이 가독성에 큰 영향을 준다 - 체크박스의 체크를 필수항목으로 설정 가능
→ 사용자에게 특정 내용에 대해 동의를 받거나 특정 사항을 이슈 작성 전에 제대로 체크했는지 강제로 리마인드하고 싶을 때 사용할 수 있다
이렇게 다양한 장점들이 있다! Issue Form 사용하자! 두번 사용하자!
여태까지 다양한 Github Issue 관련 기능들을 둘러보았지만, 전부 Github Web GUI에서 이루어지는 일들일 뿐.... Issue 관련된 여러가지 작업들은 모두 Github에서 제공하는 API를 통해 자동화가 가능하다.
이를 통해 다른 시스템에서 원격으로 이슈를 생성하거나, 이슈를 수정하고, Github Workflow와 연동하여 특정 이벤트를 받아 이슈에 자동으로 댓글을 남기고, Issue를 자동으로 Github Project에 등록하는 등등... 다양한 작업이 가능하며, 그 활용처는 정말 다양하다! 예를들어 개인 블로그에 Github 계정으로 댓글을 남길 수 있게 해주는 위젯인 Utterances는 댓글들을 저장하는 저장소로 Github Issue를 사용한다... Utterances를 위한 퍼블릭 레포지토리를 생성하고, Utterances 앱을 설치해두면, Utterance 위젯을 통해 개인 웹사이트에 달리는 댓글을 Github Issue에 저장하는 방식으로 동작한다고 한다.
언젠가 우리 프로젝트에도 더 멋진 Issue 관리 기능과 자동화 기능들을 만들어 보고 싶다!