GitHub Issues

Issues

GitHub 의 Issue 는 버그 리포트, 기능 요청, 질문, 작업 항목 등을 기록하고 추적하는 데 사용하는 토론 중심의 티켓 시스템입니다.

Issues 작성 방법

• title 및 description 작성 & 적절한 Assignees, Labels 등 지정
• 혹은 Issue Templates 을 활용하여 작성
• 제목은 일반적으로 [이슈 유형] 간결한 제목 설명 과 같은 형태로 작성
  • ex.
    • [Feature] 페이지 끝에서 자동으로 다음 페이지로 넘어가는 기능 추가
    • [Feature] Add auto-pagination when macro reaches the last page
• 설명은 자유 형식으로 서술형 응답으로 작성하면 되며, 템플릿에서 항목을 제공할 경우 항목에 맞게 작성하면 됨

Issue Templates

• 사용자가 Issue 항목을 일관성있고 편하게 작성할 수 있도록 기본적인 Issue 템플릿 제공 가능
• MD 파일 혹은 YAML 파일로 작성 가능
  • MD 파일을 사용할 경우 YAML Front Matter 를 작성해야 함

YAML Front Matter: Markdown 파일의 맨 앞에 위치하는 YAML 형식의 메타데이터 블록입니다. MD 파일을 사용해 Issue Templates 을 생성하려면 YAML Front Matter 를 작성해야합니다.

Issue Templates 선택형 템플릿 UI

• .github/ISSUE_TEMPLATE/ 아래에 여러 .md 파일이 존재해야 함
• issue templates 파일의 이름은 자유. 관행적으로 사용되는 파일명은 존재
  • 대체로 이슈의 성격 또는 카테고리에 따라 파일명 지정
    • 거의 모든 프로젝트에서 사용되는 템플릿
      • bug_report.md: 버그 리포트용
      • feature_request.md: 기능 추가 요청용
    • 그 외 자주 사용되는 템플릿
      • question.md: 일반적인 질문 또는 문의
      • support.md: 지원 요청 또는 도움 요청
      • documentation.md: 문서 관련 이슈
      • other.md: 범주에 속하지 않는 기타 이슈
      • performance_issue.md: 성능 관련 이슈
      • refactor.md: 리팩토링 제안
• 해당 구조를 따르면 GitHub 상에서 New issue 생성 시 템플릿 선택창 UI 제공
• 참고로 PR 템플릿은 UI 미제공

Issue Templates vs PR Templates

• Issue Templates
  • .github/ISSUE_TEMPLATE/ 아래에 이슈의 목적에 따라 여러 개의 템플릿을 제공하는게 일반적
• PR Templates
  • .github/ 아래에 단일 템플릿을 제공하는게 일반적

.github 폴더

• GitHub 에서 사용하는 공식적인 특수 디렉터리 (단순 관행이 아니라 GitHub 에서 기능 인식을 위해 설계된 공식 폴더)
• 저장소 수준에서 GitHub 기능을 설정하거나 문서화할 때 사용
• PR 템플릿, Issue 템플릿, CODEOWNERS, FUNDING, workflows (GitHub Actions) 등 GitHub 관련 구성 파일을 저장

Issue Templates 작성 방식

• 제목 (#, ##) 바로 아래에 공백 줄 한 칸 남기는 것이 일반적이고 권장됨
• 내용 마지막 줄 이후엔 공백 줄 남기지 않는 것이 일반적이고 권장됨
• 해당 항목에 작성할 내용이 없을 경우 공백으로 남겨두기 보다는 N/A 를 명시하는것이 일반적이고 권장됨

bug_report.md

---
name: Bug Report
about: Report a reproducible bug in this project
title: "[Bug] "
labels:
  - bug
assignees:
  - dragonHyeon
  - dragonWorker
---

## 🐛 Bug Description

A clear and concise description of what the bug is.

## 🔁 Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. See error '...'

## 🧠 Expected Behavior

What you expected to happen instead.

## 📸 Screenshots / Logs

If applicable, add screenshots or error logs to help explain your problem.

## 💻 Environment

- OS: [e.g. macOS 14, Windows 11]
- Browser / Runtime: [e.g. Chrome 120, Node.js 18]
- Version: [e.g. v1.2.3]

## 📝 Additional Context

Add any other context about the problem here.

feature_request.md

---
name: Feature Request
about: Suggest a new feature or improvement
title: "[Feature] "
labels:
  - enhancement
assignees: []
---

## 🚀 Feature Description

Clearly describe the new feature or enhancement you’re proposing.

## ✅ Use Case

Explain why this feature is needed and what problem it solves.

## 🔧 Suggested Solution

If you have an idea of how to implement it, describe it here.

## 💡 Alternatives Considered

Have you considered alternative solutions or workarounds?

## 📝 Additional Context

Add any other context or screenshots related to your request here.

question.md

---
name: Question
about: Ask a question or request clarification
title: "[Question] "
labels:
  - question
assignees:
  - dragonHyeon
---

## ❓ Question

Clearly state your question.

## 📚 What I’ve Tried

Briefly describe what you’ve tried or read before asking.

## 💬 Additional Context

Any additional information or code snippets that might help clarify your question.

• YAML Front Matter 작성
  • name, about 필드 필수 작성 (내용 또한 비면 안됨)
    • name: 템플릿 이름 (템플릿 선택 UI에 표시됨)
    • about: 템플릿 설명 (템플릿 선택 UI에 표시됨)
  • title, labels, assignees 필수 필드는 아니지만 일반적
    • title: 기본 이슈 제목
    • labels: 자동으로 붙일 라벨 (배열 또는 문자열)
    • assignees: 자동 할당할 사용자 (배열 또는 문자열)
    • labels 와 assignees 작성 방식은 아래와 같음
      • 공백은 일반적으로 [] (빈 리스트) 로 표시
      • 단일 항목 혹은 여러 항목 지정시 일반적으로 - (블록 리스트) 방식으로 작성
      • 없는 항목 작성시 존재하는 항목만 적용되고, 존재하지 않는 항목은 조용히 무시됨

Issues 자동 닫기

Pull Request 의 본문 또는 커밋 메시지 안에 특정 키워드를 작성함으로써 GitHub 에서 이슈 자동 닫기가 실행됩니다. PR 이 main (또는 default branch) 에 병합될 때, main (또는 default branch) 에 merge 되는 커밋 메시지 안에 특정 키워드를 포함시키는 경우 이슈 자동 닫기가 실행됩니다. 키워드 #이슈번호 와 같은 형태로 작성하면 됩니다.

Fixes #123
Closes #123
Resolves #123

• 지원되는 키워드 목록:
  • fix, fixes, fixed: 버그 수정
  • close, closes, closed: 기능 완료
  • resolve, resolves, resolved: 문제 해결
• 실제 동작은 모두 이슈를 자동으로 닫는 것으로 동일
  • 명령어는 의미에 맞게 사용하는 것이 선호되며, 기술적으로는 아무거나 써도 이슈는 닫힘
• fixes, closes, resolves 가 가장 선호되는 방식
  • 미래 지향적 의미를 담기 때문에 가장 선호되는 시제
• 커밋 메시지를 통한 이슈 자동 닫기보다 PR 본문에서 이슈 자동 닫기가 더 선호되는 방식
• 대소문자 구분 없음
• Pull Request 본문 예시:

### Summary

Fixes the bug where the app crashes on login

### Related Issues

Fixes #101
Closes #102

• 커밋 메시지 예시:

feat: add pagination support for post collection

- Collect posts across multiple pages until POST_COUNT is reached
- Change main loop to iterate pages and accumulate posts
- Ensure only the desired number of posts are processed

Closes #123

config.yml

GitHub 이슈 생성 화면에서 빈 이슈 허용 여부와 외부 링크 버튼 표시를 설정하는 파일입니다. .github/ISSUE_TEMPLATE/ 아래에 생성합니다.

blank_issues_enabled: true

contact_links:
  - name: ✉️ 추가 문의 (kyhps777@hanmail.net)
    url: https://github.com/dragonHyeon
    about: 템플릿에 포함되지 않은 문의 사항은 이메일로 연락해주세요.

• config.yml 작성
  • blank_issues_enabled: 사용자가 빈 이슈 (Blank issue) 를 만들 수 있는지 여부 (작성하지 않을 경우 default 는 true)
  • contact_links: UI 하단에 링크로 표시될 외부 리소스나 FAQ 링크 등

코멘트 문화

• 이슈 닫기 전 미리 댓글을 남기는게 일반적

이 이슈는 PR #45 에서 해결되었습니다.
PR 이 merge 되면 자동으로 닫힐 예정입니다. 감사합니다!

• 자동 닫기 전에 댓글을 충분히 남겼다면, 닫힌 후에는 별도로 다시 댓글을 남기지 않는 경우가 많음
• 자동 닫기 전에 까먹고 댓글을 안 남겼다면, 자동 닫기된 후에라도 댓글을 남겨주는 것이 매너

PR #45 가 merge 되면서 이슈가 자동으로 닫혔습니다.
문제는 해결되었으며, 다음 릴리스에 포함될 예정입니다. 감사합니다!

• 코멘트 작성시 한 문장 끝나고 바로 이어 붙이는 형식보다는 한 문장마다 줄을 바꾸는 형식이 더 선호
  • 두 문장을 완전히 다른 주제로 쓰면 문장과 문장 사이에 빈 줄 삽입도 가능하지만 대부분의 경우 문단까지 나눌 필요는 없음
• 마지막 줄에는 공백을 남기지 않음
• 이슈 작성자 또는 관련자에게 직접 말하는 느낌을 줄 때 @username 언급을 사용 가능
  • 멘션 (@username) 라인과 본문 라인은 짧은 문장이더라도 분리하는 것이 일반적이고 권장되는 스타일
  • 여러명을 언급할 경우 한 줄에 여러명 나열
  • @멘션 위치는 문두에 하는 것이 일반적

@dragonHyeon @dragonWorker
[본문 내용]