Quick Reference
repo/
├─ .github/
│ ├─ ISSUE_TEMPLATE/
│ │ ├─ bug_report.md
│ │ └─ feature_request.yml
│ └─ pull_request_template.md
└─ docs/
└─ PULL_REQUEST_TEMPLATE/
└─ release.md| 파일 | 역할 |
|---|---|
.github/ISSUE_TEMPLATE/*.md | Markdown issue template |
.github/ISSUE_TEMPLATE/*.yml | 구조화된 issue form |
.github/pull_request_template.md | 기본 PR template |
PULL_REQUEST_TEMPLATE/*.md | 여러 PR template |
자유 형식의 안내와 체크리스트면 Markdown issue template, 필수 입력과 선택지를 강제해야 하면 YAML issue form을 고릅니다. template file은 GitHub가 찾는 위치와 default branch에 있어야 하며, PR template은 리뷰 질문을 모으는 문서이지 test나 보안 검증을 자동 실행하지 않습니다.
구조 기준
Issue template은 새 이슈를 열 때 필요한 정보를 빠뜨리지 않게 만드는 문서입니다. Markdown template은 본문에 그대로 들어갈 안내와 체크리스트를 작성하는 방식이고, issue form은 YAML schema로 입력 필드와 required 여부를 정의하는 방식입니다.
---
name: Bug report
about: Report a reproducible bug
title: "[BUG] "
labels: bug
---
재현 절차:
1. [첫 단계]
2. [두 번째 단계]
3. [확인 결과]Issue form은 사용자가 웹 form을 채우면 결과가 표준 Markdown issue body로 변환됩니다. 입력을 구조화해야 하거나 필수 항목을 강제해야 한다면 Markdown template보다 issue form이 더 적합합니다.
PR template은 PR 본문을 표준화합니다. 변경 요약, 테스트 결과, 관련 이슈, 배포 영향 같은 항목을 미리 넣어 두면 리뷰어가 확인해야 할 정보가 안정적으로 모입니다.
선택 기준
| 상황 | 선택 |
|---|---|
| 자유로운 설명과 체크리스트 | Markdown issue template |
| 필수 입력, dropdown, checkbox 필요 | YAML issue form |
| 모든 PR에 같은 확인 항목 적용 | 기본 PR template |
| 변경 유형별 PR template 필요 | PULL_REQUEST_TEMPLATE/ 하위 template |
| 조직 전체 기본값 필요 | default community health file 검토 |
| template이 보이지 않음 | default branch 위치와 파일 확장자 확인 |
Template은 협업 규칙을 문서화하는 동시에 입력 품질을 높이는 장치입니다. 너무 많은 질문을 넣으면 작성자가 template을 지우고 제출할 수 있으므로, 실제 리뷰나 triage에 쓰는 항목만 남기는 편이 좋습니다.
주의할 점
Issue와 PR template은 저장소 default branch에 있어야 동작합니다. 다른 branch에만 추가하면 collaborators가 새 이슈나 PR을 만들 때 template을 보지 못할 수 있습니다.
Markdown issue template과 YAML issue form은 목적이 다릅니다. 구조화된 입력이 필요한데 Markdown template만 쓰면 누락을 막기 어렵고, 자유 설명이 중요한데 form을 과하게 쓰면 맥락이 잘릴 수 있습니다.
참고 링크
2 sources